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CHAPTER 1 

Introduction 



The documents on this site assume you are familiar with JavaScript or ActionScript syntax and 
with basic programming concepts such as functions, parameters, and data types. They also 
assume that you understand the concept of working with objects and properties. For a reference 
on JavaScript, see the Netscape JavaScript documentation. 

Netscape DevEdge Online has a JavaScript Developer Central site (http:// 
developer.netscape.com/tech/javascript/index.html) that contains documentation and articles 
useful for understanding JavaScript. The most valuable resource is the Core JavaScript Guide. 

This chapter contains the following sections: 

Overview of the Macromedia Flash JavaScript API 17 

The Flash Document Object Model 19 

The PolyStar example 23 

Overview of the Macromedia Flash JavaScript API 

The ActionScript language lets you write scripts to perform actions in the Macromedia Flash 
Player environment (that is, while a SWF file is playing). The Flash JavaScript API (JSAPI) lets 
you write scripts to perform several actions in the Flash authoring environment (that is, while a 
user has the Flash program open). You can write scripts that act like commands and scripts that 
add tools to the Tools panel. These scripts can be used to help automate the authoring process. 

The Flash JSAPI is designed to resemble the Macromedia Dreamweaver and Macromedia 
Fireworks JavaScript API (which were designed based on the Netscape JavaScript API). The Flash 
JSAPI is based on a Document Object Model (DOM), which allows Flash documents to be 
accessed using JavaScript objects. The Flash JSAPI includes all elements of the Netscape 
JavaScript API, plus the Flash DOM. These added objects and their methods and properties are 
described in this document. You can use any of the elements of the native JavaScript language in a 
Flash script, but only elements that make sense in the context of a Flash document will have 
an effect. 
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You can use Macromedia Flash MX 2004 Professional or your preferred text editor to write or 
edit Flash JavaScript (JSFL) files. If you use Flash Professional, these files have a .jsfl extension by 
default. To make a script appear in the Commands menu, save its JSFL file in the following 
folder: 

• Windows 2000 or Windows XP: 

C:\Documents and SettingsWMLocal Settings\ Application Data\Macromedia\ 
Flash MX2004\/<j«gw<jg<?\Configuration\Comrnands 

• Windows 98: 

C:\Windows\Application Data\Macromedia\Flash MX 2004\language\ 
Configuration\Commands 

• Mac OS X: 

Hard Drive/Users/««rAfow(?/Library/ Application Support/Macromedia/Flash MX 2004/ 
language/ Configuration/ Commands 

JSFL files that create tools need to be stored in the Tools folder, which can be found in the 
following location: 

• Windows 2000 or Windows XP: 

C:\Documents and SettingsWMLocal Settings\ Application Data\Macromedia\ 
Flash MX2004\/<j«gw<jgf?\Configuration\Tools 

• Windows 98: 

C:\Windows\Application Data\Macromedia\Flash MX 2004\/<j«gw<jg?\Configuration\Tools 

• Mac OS X: 

Hard Drive/Users/««rAfow(?/Library/ Application Support/Macromedia/Flash MX 2004/ 
language! Configuration/Tools 

If a JSFL file has other files that go with it, such as XML files, they should be stored in the same 
directory as the JSFL file. 

You can also create a JSFL file by selecting one or more commands in the History panel and then 
clicking the Save As Command button in the History panel or selecting the Save As Command 
from the Options pop-up menu. The command (JSFL) file is saved in the Commands folder. You 
can then open the file and edit it the same as any other script file. 

To run a script, do one of the following: 

• Select Commands > Command Name. 

• Select Commands > Run Command and then select the script to run. 

To add a tool implemented in a JSFL file to the Flash Tools panel: 

1. Copy the JSFL file for the tool and any other associated files to the Tools folder. 

2. Select Edit > Customize Tools Panel (Windows) or Flash > Customize Tools Panel 
(Macintosh). 

3. Add the tool to the list of available tools. 

4. Click OK. 
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You can embed individual JSAPI commands in ActionScript files by using the MMExecute ( ) 
command, which is documented in the Flash MX 2004 ActionScript Language Reference. However, 
the MMExecute( ) command has an effect only when it is used in the context of a custom user- 
interface element, such as a component Property inspector, or a SWF panel within the authoring 
environment. Even if called from ActionScript, JSAPI commands have no effect in Flash Player or 
outside the authoring environment. 

The JSAPI also contains a number of methods that let you implement extensibility using a 
combination of JavaScript and custom C code. For more information, see Chapter 4, "C-Level 
Extensibility," on page 369. 

Flash JavaScript objects contain properties and methods. Properties, each defined as a primitive 
type such as Boolean, integer, array, float, or reference data types such as color, object, point, rect, 
and String, are used to describe the object. Methods are used to perform a function on the object. 
To access the properties or methods of an object, dot notation is used. Also, most objects have 
getProperty( ) and setP roper ty() methods, which get the value for a specified property or set 
the value for a specified property. Most methods take parameters that are used to specify different 
options for the method. 

The JavaScript interpreter in Flash is the Mozilla SpiderMonkey engine, version 1.5, which is 
available on the web at http://www.mozilla.org/js/spidermonkey/. SpiderMonkey is one of the 
two reference implementations of the JavaScript language developed by Mozilla.org. It is the same 
engine that is embedded in the Mozilla browser. 

SpiderMonkey implements the entire core JavaScript language as defined in the ECMA-262 
specification. It is fully compliant with ECMA-262 Edition 3. Only the browser-specific host 
objects, which are not part of the ECMA-262 specification, are not supported. 

All "Core JavaScript" sections of Netscape's JavaScript documentation at http:// 
devedge.netscape.com/central/javascript/ apply to the Flash JavaScript interpreter. All "Client- 
Side JavaScript" sections do not apply because they only apply to browser environments. 

SpiderMonkey is also used in Fireworks MX 2004, Dreamweaver MX 2004, Director MX 2004 
and Flash Communication Server MX. 

The Flash Document Object Model 

The DOM for the Flash JavaScript API consists of a set of top-level functions (see "Top-level 
functions" on page 25) and the top-level flash object. The f 1 ash object is guaranteed to be 
available to a script because it always exists when the Flash authoring environment is open. When 
referring to this object, you can use flash or f 1 . For example, to close all open files, you can use 
either of the following statements: 

flash. closeAllO; 
fl .closeAl 1 ( ) ; 
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The fl ash object contains the following child objects: 



Object 


How to access 


componentsPanel object 


Use fl .componentsPanel to access the componentsPanel object. This 




object corresponds to the Components panel in the Flash authoring 




environment. 


Document object 


Use f 1 . documents to retrieve an array of all the open documents; use 




f 1 . documents [ i ndex] to access a particular document; use 




f 1 . getDocumentDOM( ) to access the current document (the one with 




focus). 


drawingLayer object 


Use fl .drawingfayer to access the drawingtayer object. 


Effect object 


Use f 1 . effects to retrieve an array of effect descriptors that 




corresponds to the effects registered when Flash starts; use 




f 1 .effects [index] to access a particular effect; use f 1 . acti ve Effect to 




access the effect descriptor for the current effect being applied. 


Math object 


Use f 1 . Math to access the Math object. 


outputPanel object 


Use f 1 . outputPanel to access the outputPanel object. This object 




corresponds to the Output panel in the Flash authoring environment. 


Tools object 


f 1 . tool s is an object that has a tool Ob js property. The tool Ob js 




property is an array of tool Ob j objects. Each tool Ob j object represents 




a tool in the Flash Tools panel. 


ToolObj object 


Use fl.tool s .tool Ob js to retrieve an array of all tool objects (see 




tools. toolObjs); use fl .tools. act iveTool to access the currently 




active tool object (see tool s . acti veTool). 


XMLUI object 


Use f 1 .xml ui to access an XML User Interface (XMLUI) object. The 




XMLUI object provides the ability to get and set properties of an XMLUI 




dialog box. 



The Document object 

An important property of the top-level flash object is the documents property. The documents 
property contains an array of Document objects that each represent one of the FLA files currently 
open in the authoring environment. The properties of each Document object represent most of 
the elements that a FLA file can contain. Therefore, a large portion of the DOM is composed of 
child objects and properties of the Document object. 

To refer to the first open document, for example, use the statement flash, documents [0]. or 
fl . documents [0]. The first document is the first Flash document that was opened during the 
current session in the authoring environment. When the first opened document is closed, the 
indexes of the other open documents are decremented. 

To find a particular document's index use f 1 . f i ndDocumentIndex( nameOf Document) . 

To access the document that is currently focused, use the statement flash. getDocumentDOMO or 
f 1 . getDocumentDOM ( ). The latter is the syntax used in most of the examples in this document. 

To find a particular document in the documents array, iterate through the array and test each 
document for its name property. 
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All the objects in the DOM that aren't listed in the previous table (see "The Flash Document 
Object Model" on page 19) are accessed from the Document object. For example, to access the 
library of a document, you use the libra ry property of the Document object, which retrieves a 
library object: 

f 1 . get Document DOM ( ) . 1 i brary 

To access the array of items in the library, you use the i terns property of the Li bra ry object; each 
element in the array is an Item object: 

f 1 . g et Document DOM ( ) . 1 i brary . i terns 

To access a particular item in the library, you specify a member of the i terns array: 
f 1 . get Document DOM ( ) . 1 i brary . i terns [0] 

In other words, the Li brary object is a child of the Document object, and the Item object is a 
child of the Li brary object. 

Specifying the target of an action 

Unless otherwise specified, methods affect the current focus or selection. For example, the 
following script doubles the size of the current selection because no particular object is specified: 

f 1 . ge t Document DOM ( ).scaleSelection(2, 2 ) ; 

In some cases, you might want an action to specifically target the currently selected item in the 
Flash document. To do this, use the array that the Document . sel ecti on property contains. The 
first element in the array represents the currently selected item, as shown in the following 
example: 

var accDescri pti on = f 1 . getDocumentDOM( ) . sel ecti on [0] . descri pti on ; 

The following script doubles the size of the first element on the Stage that is stored in the element 
array, instead of the current selection: 

var element = 

f 1 . ge t Document DOM ( ) . getTimel i ne ( ) .1 ayers [0] . frames [0] .el ements [0] ; 
if (element) ( 

el ement. width = element. width*2; 
el ement . hei ght = el ement . he i ght*2 ; 

1 

You can also do something such as loop through all the elements on the Stage and increase the 
width and height by a specified amount, as shown in the following example: 

var elementArray = 

f 1 . ge t Document DOM ( ) .getTimel i ne ( ) . 1 ayers [0] . frames [0] .el ements ; 
for (var i=0; i < el ementArray . 1 ength ; i++) { 
var offset = 10; 

el ementArray [i ] .width += offset; 
el ementArray [i ]. hei ght += offset; 

I 
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Summary of the DOM structure 

The following list displays the DOM structure in outline format. Numbers at the beginning of 
each line represent the level of an object. For example, an object preceded by "03" is a child of 
next highest "02" object, which, in turn, is a child of the next highest "01" object. 

In some cases, an object is available by specifying a property of its parent object. For example, the 
document. timelines property contains an array of Ti mel i ne objects. These properties are 
noted in the following outline. 

Finally, some objects are subclasses of other objects, rather than being children of other objects. 
An object that is a subclass of another object has methods and/or properties of its own in addition 
to the methods and properties of the other object (the superclass). Subclasses share the same level 
in the hierarchy as their superclass. For example, Item is a superclass of Bitmapltem. These 
relationships are illustrated in the following outline: 

01 Top-level functions 
01 flash object 

02 componentsPanel object 
02 Document object ( fl . documents array) 
03 Matrix object 
03 Fill object 
03 Stroke object 
03 library object 

04 Item object ( 1 i brary . i terns array) 
04 Bitmapltem object (subclass of Item object) 
04 folderltem object (subclass of Item object) 
04 fontltem object (subclass of Item object) 
04 Soundltem object (subclass of Item object) 
04 Symbol Item object (subclass of Item object) 
04 Videoltem object (subclass of Item object) 
03 Timeline object ( document . timel i nes array) 
04 Layer object ( timel i ne . 1 ayers array) 
05 Frame object ( 1 ayer . frames array) 

06 Element object ( frame . el ements array) 

07 Matrix object ( El ement .matri x ) 
06 Instance object (abstract class, subclass of Element object) 
06 Bi tmaplnstance object (subclass of Instance object) 
06 Compi 1 edCl i plnstance object (subclass of Instance object) 
06 Componentlnstance object (subclass of Symbol Instance object) 

07 Parameter object ( Componentlnstance . parameters ) 
06 EmbeddedVideoInstance object (subclass of Instance object) 
06 LinkedVideoInstance object (subclass of Instance object) 
06 Symbol Instance object (subclass of Instance object) 
06 Text object (subclass of Element object) 
07 TextRun object ( text . textRuns array) 

08 TextAttrs object ( textRun . textAttrs array) 
06 Shape object (subclass of Element object) 
07 Contour object ( shape . contours array) 
08 HalfEdge object 
09 Vertex object 
09 Edge object 
07 Edge object (shape. edges array) 
08 HalfEdge object 
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09 Vertex object 
09 Edge object 
07 Vertex object ( shape . verti ces array) 
08 HalfEdge object 
09 Vertex object 
09 Edge object 
03 ScreenOutl i ne object 

04 Screen object ( screenOutl i ne . screens array) 
05 Parameter object ( screen . parameters array) 
02 drawingLayer object 
03 Path object 

04 Contour object 
02 Effect object (fl. effects array) 
02 Math object 
02 outputPanel object 
02 fools object (fl. tools array) 

03 foolObj object ( tool s . tool Objs array) 
02 XMLUI object 

The PolyStar example 

Included with this documentation is a sample Flash JSAPI script named PolyStar.jsfl. (You can 
download the file at www.macromedia.com/go/jsapi_info_en.) This script replicates the PolyStar 
tool that can be found in the Flash Tools panel. The PolyStar.jsfl file demonstrates how to build 
the PolyStar tool using the JSAPI. It includes detailed comments that describe what the lines of 
code are doing. Read this file to gain a better understanding of how the JSAPI can be used. 

Flash MX 2004 includes an earlier version of the PolyStar.jsfl script that must be removed in order 
to use the updated PolyStar.jsfl file. 

To remove the earlier version of the PolyStar.jsfl that was installed with Flash MX 2004: 

1. Select Edit > Customize Tools Panel (Windows) or Flash > Customize Tools Panel 
(Macintosh). 

2. In the Customize Tools Panel dialog box, click the Rectangle tool on the left side of the dialog 
box. 

The Rectangle tool and the PolyStar tool should now be listed in the Current Selection list on 
the right side of the dialog box. 

3. Select the PolyStar tool in the Current Selection list. 

4. Click Remove. 

5. Click OK. 

6. Quit Flash. 

7. Remove only the PolyStar.jsfl file from the appropriate Tools folder listed in "Overview of the 
Macromedia Flash JavaScript API" on page 17. The PolyStar.xml and PolyStar.png files are 
needed by the new PolyStar.jsfl file that you will install later. When you restart Flash, the 
PolyStar tool no longer appears in the Customize Tools Panel dialog box. 
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To install the updated PolyStar example files: 

1. Copy the new PolyStar.jsfl file to the Tools folder. The PolyStar.xml and PolyStar.png files that 
you see in this folder are needed by the new PolyStar.jsfl file. 

2. Restart Flash. 

3. Select Edit > Customize Tools Panel (Windows) or Flash > Customize Tools Panel 
(Macintosh). You should see PolyStar tool in the available tools list. 

4. Click the Rectangle tool at the left side of the Customize Tools Panel dialog box. The Rectangle 
Tool should appear in the Current Selection list at the right side of the dialog box. 

5. Select the PolyStar tool from the Available Tools list. 

6. Click Add. 

7. Click OK. 

The PolyStar tool now appears in the Rectangle tool pop-up menu. 
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CHAPTER 2 

Top-level functions 



This chapter describes the top-level functions that are available when creating extensible tools. 
The following list shows the functions in alphabetical order: 

a c t i v a t e ( ) 
configureEffecU ) 
conf i gureTool ( ) 
deacti vate ( ) 
executeEf f ect ( ) 
keyDown ( ) 
keyUpt ) 

mouseDoubl eCl i ck( ) 
mouseDown ( ) 
mouseMove ( ) 
mouseUpt ) 

not ify Sett ingsChangedO 
removeEf f ect ( ) 
setCursor ( ) 
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activateQ 



Availability 

Flash MX 2004. 

Usage 

function activatet) j 
// statements 

( 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called when the extensible tool becomes active (that is, when the tool is selected 
in the Tools panel). Any setup the tool needs to do should be performed in this function. 

Example 

function activatet) j 

fl.tracet "fool is active" ); 

I 
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configureEffect() 

Availability 

Flash MX 2004. 
Usage 

function conf i gureEf f ect ( ) j 
// statements 

} 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called once at load time of Flash and is a good place for global initialization of 
your effect. The per instance parameter data for an effect cannot be accessed here. 

See also 

executeEf f ect ( ), removeEf f ect ( ) 
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configureTool() 

Availability 

Flash MX 2004. 
Usage 

function conf i gureTool ( ) j 
// statements 

I 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called when Macromedia Flash opens and the tool is loaded. Use this function to 
set any information Flash needs to know about the tool. 

Example 

The following examples show two possible implementations of this function: 

function conf i guref ool ( ) j 

thefool = f 1 . tool s . acti vef ool ; 

thef ool . setf ool Name ( "my fool " ) ; 

thefool . set Icon ( "my fool . png" ) ; 

thef ool . setMenuStri ng ( "My fool's menu string"); 

thef ool . setf ool fi p( "my tool's tool tip"); 

thef ool . setOpti ons Fi 1 e ( "mtfool.xml" ); 

I 

function conf i guref ool ( ) j 

thefool = f 1 . tool s . acti vef ool ; 
thefool . setf ool Name ( "el 1 i pse" ) ; 
thefool . set Icon ( " El 1 i pse . png" ) ; 
thefool . setMenuStri ng ( " El 1 i pse" ) ; 
thefool . setf ool f i p( " El 1 i pse" ) ; 
thef ool . showfransf ormHandl es ( true ); 

) 
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deactivate() 



Availability 

Flash MX 2004. 
Usage 

function deacti vate ( ) j 
// statements 

( 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called when the tool becomes inactive (that is, when the active tool changes from 
this tool to another one). Use this function to perform any cleanup the tool needs. 

Example 

function deacti vate ( ) j 

fl.tracet "fool is no longer active" ); 

I 
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executeEffect() 

Availability 

Flash MX 2004. 
Usage 

function executeEf f ect ( ) j 
// statements 

} 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called when the user first applies an effect or changes an effect's properties. The 
code contained in this function is responsible for modifying the original object(s) to accomplish 
the desired effect. It is also responsible for copying the original to another hidden layer if 
necessary for the removeEffect function 

See also 

configureEffect( ), removeEf fect( ) 
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keyDown() 

Availability 

Flash MX 2004. 

Usage 

f uncti on keyDown ( ) { 
// statements 

} 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called when the tool is active and the user presses a key. The script should call 
tool s . getKeyDown ( ) to determine which key was pressed. 

Example 

function keyDownO ( 

f 1 . tracet " key " + fl . tool s . getKeyDown ( ) + " was pressed"); 

} 
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keyUp() 

Availability 

Flash MX 2004. 

Usage 

function keyllpt) j 
// statements 

( 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called when the tool is active and a key is released. 

Example 

function keyllpt) j 

f 1 . trace( " Key is released"); 

( 
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mouseDoubleClickO 

Availability 

Flash MX 2004. 
Usage 

function mouseDoubl eCl i ck( ) j 
// statements 

( 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called when the mouse button is double-clicked on the Stage. 

Example 

function mouseDbl CI k( ) j 

fl . trace( "Mouse was doubl e - cl i eked" ) ; 

( 
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mouseDown() 



Availability 

Flash MX 2004. 
Usage 

function mouseDown( [ pt ] ) { 
// statements 

( 

Parameters 

pt A point that specifies the location of the mouse when the button is pressed. It is passed to the 
function when the mouse button is pressed. This parameter is optional. 

Returns 

Nothing. 
Description 

This function is called whenever the tool is active and the mouse button is pressed while the 
pointer is over the Stage. 

Example 

function mouseDownU j 

fl . tracet "Mouse button has been pressed"); 

) 
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mouseMove() 



Availability 

Flash MX 2004. 
Usage 

function mouseMove( [ pt ] ) { 
// statements 

( 



Parameters 

pt A point that specifies the current location of the mouse. It is passed to the function whenever 
the mouse moves, which tracks the mouse location. If the Stage is in edit or edit-in-place mode, 
the point coordinates are relative to the object being edited. Otherwise, the point coordinates are 
relative to the Stage. This parameter is optional. 

Returns 

Nothing. 
Description 

This function is called whenever the mouse moves over a specified point on the Stage. The mouse 
button can be down or up. 

Example 

f uncti on mouseMove ( ) j 
f 1 . trace( "movi ng" ) ; 

( 
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mouseUp() 

Availability 

Flash MX 2004. 

Usage 

f uncti on mouseUp( ) j 
// statements 

( 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called whenever the mouse button is released after being pressed on the Stage. 

Example 

function mousellpt) j 

f 1 . tracet "mouse i s up" ) ; 

) 
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notifySettingsChanged() 

Availability 

Flash MX 2004. 
Usage 

function noti fySetti ngsChanged ( ) { 
// statements 

} 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called whenever a tool is active and the user changes its options in the Property 
inspector. You can use the tools, act iveTool property to query the current values of the 
options. 

Example 

function noti fySetti ngsChanged ( ) { 
var thefool = f 1 . tool s . acti vef ool ; 
var newValue = thefool .myProp ; 

} 
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removeEffect() 

Availability 

Flash MX 2004. 
Usage 

function removeEf f ect ( ) j 
// statements 

} 

Parameters 

None. 



Returns 

Nothing. 
Description 

This function is called when the user changes an effect's properties or uses the "remove effect" 
menu item. The code contained in this function is responsible for returning the object(s) to their 
original state. For example, if the effect broke a text string apart, the responsibility of the 
removeEf feet ( ) method would be to remove the text string that was broken apart and replace it 
with the original string. 

See also 

configureEffect( ), executeEf fect( ) 
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setCursor() 



Availability 

Flash MX 2004. 
Usage 

function setCursorU ( 
// statements 

} 

Parameters 

None. 
Returns 

Nothing. 
Description 

This function is called whenever the mouse moves, to allow the script to set custom pointers. The 
script should call tools. setCursorO to specify the pointer to use. For a list that shows which 
pointers correspond to which integer values, see tools.setCursort). 

Example 

function setCursorU ( 
f 1 . tool s . setCursor ( 1 ); 

} 
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CHAPTER 3 

Objects 



This chapter describes the Flash JSAPI objects, listed in alphabetical order. The objects are listed 
in the following table: 



Object 



Description 



Bitmaplnstance object 
Bitmapltem object 
CompiledCliplnstance object 
Componentlnstance object 
componentsPanel object 

Contour object 

Document object 
drawingLayer object 

Edge object 

Effect object 

Element object 

EmbeddedVideolnstance 
object 

Fill object 

flash object 
folderltem object 



The Bitmaplnstance object is a subclass of the Instance object and 
represents a bitmap in a frame. 

A Bitmapltem object refers to a bitmap in the library of a document. 
The Bitmapltem object is a subclass of the Item object. 

The CompiledCliplnstance object is a subclass of the Instance 
object. 

The Componentlnstance object is a subclass of the Symbollnstance 
object and represents a component in a frame. 

The componentsPanel object, which represents the Components 
panel, is a property of the flash object and can be accessed by 
f 1 . componentsPanel . 

A Contour object represents a closed path of half edges on the 
boundary of a shape. 

The Document object represents the Stage. 

The drawingLayer object is accessible from JavaScript as a child of 
the flash object. 

The Edge object represents an edge of a shape on the Stage. 

The Effect object represents an instance of a Timeline effect. 

Everything that appears on the Stage is of the type Element. 

The EmbeddedVideolnstance object is a subclass of the Instance 
object. 

The Fill object contains all the properties of the Fill color setting of 
the Tools panel or of a selected shape. 

The flash object represents the Flash application. 

The folderltem object is a subclass of the Item object. 
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Object 



Description 



fontltem object 
Frame object 
HalfEdge object 
Instance object 
Item object 
Layer object 
library object 

LinkedVideolnstance object 
Math object 

Matrix object 
outputPanel object 

Parameter object 



Path object 

Screen object 
ScreenOutline object 
Shape object 

Soundltem object 

Stroke object 

Symbollnstance object 

Symbolltem object 
Text object 
TextAttrs object 



The fontltem object is a subclass of the Item object. 

The Frame object represents frames in the layer. 

Directed side of the edge of a Shape object. 

The Instance object is a subclass of the Element object. 

The Item object is an abstract base class. 

The Layer object represents a layer in the Timeline. 

The library object represents the Library panel. 

The LinkedVideolnstance object is a subclass of the Instance object. 

The Math object is available as a read-only property of the flash 
object; see fl .Math. 

The Matrix object represents a transformation matrix. 

The outputPanel object represents the Output panel, which displays 
troubleshooting information such as syntax errors. 

The Parameter object type is accessed from the screen . parameters 
array (which corresponds to the screen Property inspector in the 
Flash authoring tool) or by the component Instance, parameters array 
(which corresponds to the component Property inspector in the 
authoring tool). 

The Path object defines a sequence of line segments (straight, 
curved, or both), which you typically use when creating extensible 
tools. 

The Screen object represents a single screen in a slide or form 
document. 

The ScreenOutline object represents the group of screens in a slide 
or form document. 

The Shape object is a subclass of the Element object. The Shape 
object provides more precise control than the drawing APIs for 
manipulating or creating geometry on the Stage. 

The Soundltem object is a subclass of the Item object. It represents 
a library item used to create a sound. 

The Stroke object contains all the settings for a stroke, including the 
custom settings. 

The Symbollnstance object is a subclass of the Instance object and 
represents a symbol in a frame. 

The Symbolltem object is a subclass of the Item object. 

The Text object represents a single text item in a document. 

The TextAttrs object contains all the properties of text that can be 
applied to a subselection. This object is a subclass of the Text 
object. 
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Object 


Description 


TextRun object 


The TextRun object represents a run of characters that have 




attributes that match all of the properties in the TextAttrs object. 


Timeline object 


The Timeline object represents the Flash Timeline, which can be 




accessed for the current document by 




f 1 . get Document DOM ( ) . getTi mel i ne( ) . 


TnolOhi rthippt 


A TnnlOhi nhippt rpnrpspnt^ an inHivirli i^l tool in thp Tnnls nanpl 
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Tools object 


The Tools object is accessible from the Flash object (f 1 . tool s). 


Vertex object 


The Vertex object is the part of the shape data structure that holds 




the coordinate data. 


Videoltem object 


The Videoltem object is a subclass of the Item object. 


XMLUI object 


The XMLUI object provides the ability to get and set properties of an 




XMLUI dialog box, and accept or cancel out of one. 



Bitmaplnstance object 

Inheritance Element object > Instance object > Bitmaplnstance object 
Availability 

Flash MX 2004. 
Description 

The Bitmaplnstance object is a subclass of the Instance object and represents a bitmap in a frame. 

Method summary for the Bitmaplnstance object 

In addition to the Instance object methods, you can use the following methods with the 
Bitmaplnstance object: 



Method 


Description 


bitmapInstance.getBI ts( ) 


Method; lets you create bitmap effects by getting the bits out of the 




bitmap, manipulating them, and then returning them to Flash. 


bitmapInstance.setBi ts( ) 


Method; sets the bits of an existing bitmap element. 



Property summary for the Bitmaplnstance object 

In addition to the Instance object properties, you can use the following properties with the 
Bitmaplnstance object. 

Property Description 

bi tmap Instance. hPixel s Read-only; an integer that represents the width of the bitmap, in 

pixels. 

bi tmap Instance. vPixel s Read-only; an integer that represents the height of the bitmap, in 

pixels. 
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bitmaplnstance.getBitsQ 



Availability 

Flash MX 2004. 
Usage 

bi tmaplnstance . getBi ts ( ) 
Parameters 

None. 
Returns 

An object that contains wi dth, hei ght, depth, bi ts, and, if the bitmap has a color table, cTab 
properties. The bi ts element is an array of bytes. The cTab element is an array of color values of 
the form "#rrggbb". The length of the array is the length of the color table. 

Note: The byte array is meaningful only when referenced by an external library. You typically use it 
only when creating an extensible tool or effect. 

Description 

Method; lets you create bitmap effects by getting the bits out of the bitmap, manipulating them, 
and then returning them to Flash. See also b i tmaplnstance. s e t B i t s ( ). 

Example 

The following code creates a reference to the currently selected object; tests whether the object is a 
bitmap; and traces the height, width, and bit depth of the bitmap: 

var isBitmap = f 1 . getDocumentDOM( ) . sel ecti on [0] . i nstanceType ; 
iftisBitmap == "bitmap") I 

var bits = fl . getDocumentDOMt ). sel ecti on [0] . getBi ts () ; 

fl . tracet " hei ght = " + bi ts . hei ght ) ; 

fl . tracet "width = " + bits. width); 

fl . tracet "depth = " + bits. depth); 

} 

bitmaplnstance.hPixels 

Availability 

Flash MX 2004. 
Usage 

bi tmaplnstance. hPixels 
Description 

Read-only property; an integer that represents the width of the bitmap, in pixels. 
Example 

The following code retrieves the width of the bitmap in pixels: 

// Get the number of pixels in the horizontal dimension, 
var bmObj = fl . getDocumentDOMt ). sel ecti on [0] ; 
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var isBitmap = bmObj . i nstanceType ; 
iftisBitmap == "bitmap")! 

var numHori zontal Pi xel s = bmObj . hPi xel s ; 

I 

bitmaplnstance.setBits() 

Availability 

Flash MX 2004. 
Usage 

bitmapInstance.setBits {bitmap) 
Parameters 

bi tmap An object that contains height, width, depth, bits, and cTab properties. The 
height, width, and depth properties are integers. The bits property is a byte array. The cTab 
property is required only for bitmaps with a bit depth of 8 or less and is a string that represents a 
color value in the form " # r r g g b b " . 

Note: The byte array is meaningful only when referenced by an external library. You typically use it 
only when creating an extensible tool or effect. 

Returns 

Nothing. 
Description 

Method; sets the bits of an existing bitmap element. This lets you create bitmap effects by getting 
the bits out of the bitmap, manipulating them, and then returning the bitmap to Flash. 

Example 

The following code tests whether the current selection is a bitmap, and then reduces the height of 
the bitmap by 150 pixels: 

var isBitmap = fl . getDocumentDOM( ). sel ecti on [0] . i nstanceType ; 
iftisBitmap == "bitmap")! 

var bits = f 1 . getDocumentDOM( ) . sel ecti on [0] . getBi ts ( ) ; 

bits. height = -150; 

f 1 . get Document DOM ( ). select ion[0].setBits(bits); 

I 

bitmaplnstance.vPixels 

Availability 

Flash MX 2004. 
Usage 

bitmaplnstance.vPixels 
Description 

Read-only property; an integer that represents the height of the bitmap, in pixels. 
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Example 

The following code gets the height of the bitmap in pixels: 

// get the number of pixels in the vertical dimension 
var bmObj = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
var isBitmap = bmObj . i nstanceType ; 
iftisBitmap == "bitmap")! 

var numVerti cal Pi xel s = bmObj . vPi xel s ; 

} 
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Bitmapltem object 

Inheritance Item object > Bitmapltem object 
Availability 

Flash MX 2004. 
Description 

A Bitmapltem object refers to a bitmap in the library of a document. The Bitmapltem object is a 
subclass of the Item object. 

Property summary for the Bitmapltem object 

In addition to the Item object properties, the Bitmapltem object has following properties: 
Property Description 

bi tmapltem. al 1 owSmoothi ng Property; a Boolean value. Set to true to allow smoothing of 

a bitmap; f al se otherwise. 

bi tmapltem. compress ionType Property; a string that determines the type of image 

compression applied to the bitmap. 

bi tmapltem. qua 1 i ty Property; an iinteger that specifies the quality of the bitmap 

bi tmapltem. uselmportedJPEGQual i ty Property; a Boolean value. To use the default imported JPEG 

quality, specify true; f al se otherwise. 



bitmapltem.allowSmoothing 

Availability 

Flash MX 2004. 
Usage 

bi tmapltem. al 1 owSmoothi ng 
Description 

Property; a Boolean value. Set to true to allow smoothing of a bitmap; false otherwise. 
Example 

The following code sets the al 1 owSmoothi ng property of the first item in the library of the 
current document to true: 

fl . getDocumentDOMt ). 1 i brary . i terns [0] . al 1 owSmoothi ng = true; 
al ert ( f 1 . getDocumentDOMt ) . 1 i brary . i terns [0] . al 1 owSmoothi ng ) ; 
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bitmapltem.compressionType 

Availability 

Flash MX 2004. 
Usage 

bi tmapltem. compressi onType 
Description 

Property; a string that determines the type of image compression applied to the bitmap. 
Acceptable values are "photo" or "1 os si ess ". If bi tmapltem . use Imported J PEGQual i ty is 
false, "photo" corresponds to JPEG using a quality from 0 to 1 00; if 
bi tmapltem. use Imported J PEGQual i ty is true, "photo" corresponds to JPEG using the 
default document quality value. The value "lossless" corresponds to GIF or PNG formats. 

Example 

The following code sets the comp res si onType property of the first item in the library of the 
current document to "photo": 

f 1 . get Document DOM ( ) . 1 i brary . i terns [0] .compressi onType = "photo"; 
al ert ( f 1 . get Document DOM ( ) . 1 i brary . i terns [0] . compressi onType ) ; 

bitmapltem. quality 

Availability 

Flash MX 2004. 

Usage 

bitmapltem. qual i ty 

Description 

Property; an integer that specifies the quality of the bitmap. To use the default document quality, 
specify -1; otherwise, specify an integer from 0 to 100. Available only for JPEG compression. 

Example 

The following code sets the qual i ty property of the first item in the library of the current 
document to 65: 

fl . getDocumentDOMt ). 1 i brary . i terns [0] . qual i ty = 65; 
al ert ( f 1 . get Document DOM ( ) . 1 i brary . i terns [0] .qual i ty ) ; 

bitmapltem. uselmportedJPEGQuality 

Availability 

Flash MX 2004. 

Usage 

bi tmapltem. use Import ed J PEGQual i ty 
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Description 

Property; a Boolean value. To use the default imported JPEG quality, specify true; false 
otherwise. Available only for JPEG compression. 

Example 

The following code sets the uselmportedJPEGQuality property of the first item in the library of 
the current document to true: 

f 1 . get Document DOM ( ) . 1 i brary . i terns [0] . use Imported J PEGQual i ty = true ; 
al ert ( f 1 . ge t Document DOM ( ) . 1 i brary . i terns [0] . use Imported J PEGQual i ty ) ; 
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CompiledCliplnstance object 

Inheritance Element object > Instance object > CompiledCliplnstance object 
Availability 

Flash MX 2004. 
Description 

The CompiledCliplnstance object is a subclass of the Instance object. It is essentially an instance 
of a movie clip that has been converted to a compiled clip library item. 

Property summary for the CompiledCliplnstance object 

In addition to the properties of the Instance object, the CompiledCliplnstance object has the 
following properties: 



Property Description 

compi ledClipInstance.accName Property; a string that is equivalent to the Name field in the 

Accessibility panel. 

compi 1 edCl i p Instance. actionScri pt Property; a string that represents the ActionScript for this 

instance; equivalent to symbol Instance, acti onScri pt. 

compi ledClipInstance.description Property; a string that is equivalent to the Description field in 

the Accessibility panel. 

compi 1 edCl i p Instance . f orceSi mpl e Property; a Boolean value that enables and disables the 

children of the object to be accessible. 

compi ledClipInstance. shortcut Property; a string that is equivalent to the Shortcut field in the 

Accessibility panel. 

compi 1 edCl i plnstance. si 1 ent Property; a Boolean value that enables or disables the 

accessibility of the object; equivalent to the inverse logic of 
Make Object Accessible setting in the Accessibility panel. 

compi 1 edCl i plnstance. tablndex Property; an integer that is equivalent to the Tab Index field in 

the Accessibility panel. 



compiledCliplnstance.accName 

Availability 

Flash MX 2004. 
Usage 

compi led CI i plnstance. accName 
Description 

Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers 
identify objects by reading the name aloud. 
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Example 

// get the name of the object. 

var theName = f 1 . getDocumentDOM( ) . sel ecti on [0] . accName ; 
// set the name of the object. 

fl . getDocumentDOM( ). sel ecti on[0] . accName = 'Home Button'; 

compiledCliplnstance.actionScript 

Availability 

Flash MX 2004. 
Usage 

compi ledClipInstance.actionScript 
Description 

Property; a string that represents the ActionScript for this instance; equivalent to 

symbol Instance. act ionScript. 

Example 

The following code assigns ActionScript to specified elements: 

//assign some ActionScript to a specified Button compiled clip instance, 
f 1 . ge t Document DOM ( ).getTimeline().layers[0].frames[0].el ements [0] 

. acti onScri pt = "on(click) { tracet ' button is clicked');!"; 
//assign some ActionScript to the currently selected Button compiled clip 

i nstance . 

f 1 . ge t Document DOM ( ). select ion[0]. act ionScript = 
"on(click) { tracet ' button is clicked');)"; 

compiledCliplnstance.description 

Availability 

Flash MX 2004. 
Usage 

compi 1 ed CI iplnstance. description 
Description 

Property; a string that is equivalent to the Description field in the Accessibility panel. The 
description is read by the screen reader. 

Example 

The following example illustrates getting and setting the description property: 
// get the description of the current selection 

var theDescri pti on = f 1 . getDocumentD0M( ) . sel ecti on [0] . descri pti on ; 
// set the description of the current selection 
f 1 . get Document DOM ( ). select ion[0]. description = 
"This is compiled clip number 1"; 
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compiledCliplnstance.forceSimple 



Availability 

Flash MX 2004. 
Usage 

compi led CI iplnstance. forces imple 
Description 

Property; a Boolean value that enables and disables the children of the object to be accessible. 
This is equivalent to the inverse logic of the Make Child Objects Accessible setting in the 
Accessibility panel. If f orceSi mpl e is true, it is the same as the Make Child Objects Accessible 
option being unchecked. If f orceSi mpl e is f al se, it is the same as the Make Child Object 
Accessible option being checked. 

Example 

The following example illustrates getting and setting the forceSimple property: 
// query if the children of the object are accessible 

var a reChi 1 drenAccessi bl e = fl . getDocumentDOM( ). sel ecti on [0] . f orceSi mpl e ; 
// allow the children of the object to be accessible 
fl . getDocumentDOMt ). sel ecti on [0] . f orceSi mpl e = false; 



compiledCliplnstance.shortcut 

Availability 

Flash MX 2004. 
Usage 

compi led CI iplnstance. shortcut 
Description 

Property; a string that is equivalent to the Shortcut field in the Accessibility panel. The shortcut is 
read by the screen readers. This property is not available for dynamic text fields. 

Example 

The following example illustrates getting and setting the shortcut property: 
// get the shortcut key of the object 

var theShortcut = fl . getDocumentD0M( ). sel ecti on [0] . shortcut ; 

// set the shortcut key of the object 

fl . getDocumentDOMt ). sel ecti on[0] . shortcut = "Ctrl+I"; 



compiledCliplnstance.silent 

Availability 

Flash MX 2004. 
Usage 

compi led CI iplnstance. si lent 
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Description 

Property; a Boolean value that enables or disables the accessibility of the object; equivalent to the 
inverse logic of Make Object Accessible setting in the Accessibility panel. That is, if si 1 en t is 
true, then Make Object Accessible is unchecked. If si 1 ent is fal se, then Make Object 
Accessible is checked. 

Example 

The following example illustrates getting and setting the si 1 ent property: 

// query if the object is accessible 

var isSilent =f 1 . getDocumentDOM( ) . sel ecti on [0] . si 1 ent ; 

// set the object to be accessible 

f 1 . getDocumentDOM( ) . sel ecti on[0] . si 1 ent = false; 



compiledCliplnstance.tablndex 

Availability 

Flash MX 2004. 
Usage 

compi ledClipInstance.tablndex 
Description 

Property; an integer that is equivalent to the Tab Index field in the Accessibility panel. Creates a 
tab order in which objects are accessed when the user presses the Tab key. 

Example 

The following example illustrates getting and setting the tab Index property: 
// get the tablndex of the object. 

var theTablndex = f 1 . getDocumentDOM( ) . sel ecti on [0] . tabl ndex ; 

// set the tablndex of the object. 

f 1 . getDocumentDOM( ) . sel e ction[0] .tablndex = 1; 
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Componentlnstance object 

Inheritance Element object > Instance object > Symbollnstance object > Componentlnstance 
object 

Availability 

Flash MX 2004. 
Description 

The Componentlnstance object is a subclass of the Symbollnstance object and represents a 
component in a frame. 

Property summary for the Componentlnstance object 

In addition to all the properties of the Symbollnstance object, the Componentlnstance object has 
the following property: 

Property Description 

componentlnstance .parameters Read-only; an array containing the ActionScript 2.0 properties that 

are accessible from the component Property inspector. 

componentlnstance. parameters 

Availability 

Flash MX 2004. 
Usage 

componentlnstance . parameters 
Description 

Read-only property; an array containing the ActionScript 2.0 properties that are accessible from 
the component Property inspector. See "Parameter object" on page 237. 

Example 

The following example illustrates getting and setting the parameters property: 

var parms = fl . getDocumentD0M( ). sel ecti on [0] . parameters ; 
parms[0] . val ue = "some value"; 
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componentsPanel object 

Availability 

Flash MX 2004. 
Description 

The componentsPanel object, which represents the Components panel, is a property of the flash 
object and can be accessed by f 1 . componentsPanel . 

Method summary for the ComponentsPanel object 

You can use the following method with the componentsPanel object: 
Property Description 

componentsPanel . addltemToDocumentf ) Adds the specified component to the document at the 

specified position. 

componentsPanel.addltemToDocumentO 

Availability 

Flash MX 2004. 
Usage 

componentsPanel . addItemToDocument( position, categoryName , componentName ) 
Parameters 

posit / on A point (for example, {x:0, y : 1 00}) that specifies the location at which to add the 
component. Specify posit i on relative to the center point of the component — not the 
component's registration point. 

categoryName A string that specifies the name of the component category (for example, "Data 
Components"). The valid category names are listed in the Components panel. 

componentName A string that specifies the name of the component in the specified category 
(for example, "WebServiceConnector"). The valid component names are listed in the 
Components panel. 

Returns 

Nothing. 
Description 

Adds the specified component to the document at the specified position. 
Examples 

The following examples illustrate some ways to use this method: 

fl .componentsPanel . addItemToDocument( {x:0, y:0), "UI Components", "CheckBox"); 
fl .componentsPanel . addItemToDocument( {x:0, y:1001, "Data Components", 

"WebServiceConnector") ; 
fl .componentsPanel . addItemToDocument( {x:0, y:200), "UI Components", "Button"); 
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Contour object 

Availability 

Flash MX 2004. 
Description 

A Contour object represents a closed path of half edges on the boundary of a shape. 

Method summary for the Contour object 

You can use the following method with the Contour object: 
Property Description 

contour.getHalfEdgeO Method; returns a Half Edge object on the contour of the selection. 

Property summary for the Contour object 

You can use the following properties with the Contour object: 
Property Description 

contour, i nterior Read-only: the value is true if the contour encloses an area; fal se 

otherwise. 

contour .ori entati on Read-only; an integer indicating the orientation of the contour. 

contour.getHalfEdgeO 

Availability 

Flash MX 2004. 

Usage 

contour. getHa If Ed ge() 

Parameters 

None. 
Returns 

A HalfEdge object. 
Description 

Method; returns a HalfEdge object on the contour of the selection. 
Example 

This example traverses all the contours of a selected shape and shows the coordinates of the 
vertices in the Output panel: 

// with a shape selected 

var elt = f 1 . getDocumentDOM( ) . sel ecti on[0] ; 
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el t . begi n Ed i t ( ) ; 

var contourArray = el t . contours ; 
var contourCount = 0; 

for (i=0; i <contourArray . 1 ength ; i++) 

( 

var contour = contourArray [i ] ; 
contourCount++; 

var he = contour . getHal f Edge () ; 

var i Start = he. id; 

var id = 0 ; 

while (id != iStart) 

( 

// get the next vertex 
var vrt = he.getVertex( ) ; 



var x = vrt.x; 
var y = vrt.y ; 

f 1 . tracet " vrt : " + x + " , " + y ) ; 

he = he . getNext ( ) ; 
id = h e . i d ; 

I 

I 

elt.endEditO; 

contour.interior 

Availability 

Flash MX 2004. 

Usage 

contour . i nteri or 

Description 

Read-only property: the value is true if the contour encloses an area; false otherwise. 
Example 

This example traverses all the contours in the selected shape and shows the value of the interior 
property for each contour in the Output panel: 

var elt = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
el t . begi n Ed i t ( ) ; 

var contourArray = el t . contours ; 
var contourCount = 0; 

for (i=0; i <contourArray . 1 ength ; i++) { 
var contour = contourArray [i ] ; 

fl . tracet "Next Contour, interior:" + contour.interior ); 
contourCount++; 
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I 

elt.endEditO ; 



contour.orientation 

Availability 

Flash MX 2004. 

Usage 

contour . ori entati on 

Description 

Read-only property: an integer indicating the orientation of the contour. The value of the integer 
is - 1 if the orientation is counterclockwise, 1 if it is clockwise, and 0 if it is a contour with no area. 

Example 

The following example traverses all the contours of the selected shape and shows the value of the 
orientation property of each contour in the Output panel: 

var elt = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
el t . begi nEdi t ( ) ; 

var contourArray = el t . contours ; 
var contourCount = 0; 

for (i=0; i <contourArray . 1 ength ; i++) { 
var contour = contourArray [i ] ; 

f 1 . tracet "Next Contour, orientation:" + contour.orientation); 
contourCount++; 

( 

elt.endEditO ; 
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Document object 

Availability 

Flash MX 2004. 
Description 

The Document object represents the Stage. That is, only FLA files are considered documents. 

Method summary for the Document object 

You can use the following methods with the Document object. 



Method 



Description 



document.addDataToDocumentO 
document . addDataToSel ecti on ( ) 
document. addltemt ) 

document . add New Li ne( ) 
document . addNewOval ( ) 
document . addNewPublishProfile() 
document .addNewRectanglet ) 

document .addNewSceneO 

document . addNewText( ) 
document . al i gn ( ) 
document. all owScreens( ) 

document. arranget ) 
document. breakApart( ) 

document. canEditSymbol ( ) 

document. can Revert ( ) 

document . canTestMovi e( ) 

document . canTestScene( ) 

document . cl i pCopy( ) 



Stores specified data with a document. 

Stores specified data with the selected object(s). 

Adds an item from any open document or library to the 
specified Document object. 

Adds a new path between two points. 

Adds a new oval in the specified bounding rectangle. 

Adds a new publish profile and makes it the current one. 

Adds a new rectangle or rounded rectangle, fitting it into 
the specified bounds. 

Adds a new scene (Timeline object) as the next scene 
after the currently selected scene and makes the new 
scene the currently selected scene. 

Inserts a new empty text field. 

Aligns the selection. 

Use this method before using the 
document . screenOutl i ne property. 

Arranges the selection on the Stage. 

Performs a break-apart operation on the current 
selection. 

Indicates whether Edit Symbols menu and functionality 
is enabled. 

Determines whether you can use the document. revert( ) 
or fl . revertDocumentt ) method successfully. 

Determines whether you can use the 
document . testMoviet ) method successfully. 

Determines whether you can use the 

document . testScenet ) method successfully. 

Copies the current selection from the document to the 
Clipboard. 
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Method 



Description 



document . cl i pCut ( ) 

document .clipPastet) 

document . closet) 

document .convertLinesToFillst) 

document . convertToSymbol ( ) 

document.deletePublishProfilet) 

document . deleteScenet) 

document .deleteSelectiont) 
document .distributet) 
document . distributeTo Layers () 

document. documentHasData ( ) 

document . duplicatePublishProfilet) 

document .duplicateScenet) 

document .dupl icateSel ectiont ) 
document .editScenet) 

document. enter Ed itModet) 

document. ex itEditModet ) 

document . exportPublishProfilet) 
document . export SW Ft) 

document .getAlignToDocumentt) 

document.getCustomFillt) 

document. getCustomStroket) 



Cuts the current selection from the document and writes 
it to the Clipboard. 

Pastes the contents of the Clipboard into the document. 

Closes the specified document. 

Converts lines to fills on the selected objects. 

Converts the selected Stage item(s) to a new symbol. 

Deletes the currently active profile, if there is more than 
one. 

Deletes the current scene (Timeline object) and, if the 
deleted scene was not the last one, sets the next scene 
as the current Timeline object. 

Deletes the current selection on the Stage. 

Distributes the selection. 

Performs a distribute-to-layers operation on the current 
selection; equivalent to selecting Distribute to Layers. 

Checks the document for persistent data with the 
specified name. 

Duplicates the currently active profile and gives the 
duplicate version focus. 

Makes a copy of the currently selected scene, giving the 
new scene a unique name and making it the current 
scene. 

Duplicates the selection on the Stage. 

Makes the specified scene the currently selected scene 
for editing. 

Switches the authoring tool into the editing mode 
specified by the parameter. 

Exits from symbol-editing mode and returns focus to the 
next level up from the editing mode. 

Exports the currently active profile to a file. 

Exports the document to the specified file in the Flash 
SWF format. 

Identical to retrieving the value of the To Stage button in 
the Align panel. 

Retrieves the fill object of the selected shape or, if 
specified, the toolbar and Property inspector. 

Returns the stroke object of the selected shape or, if 
specified, the toolbar and Property inspector. 



document. getDataFromDocumentt ) 



Retrieves the value of the specified data. 
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Method Description 



document . get El ement Property ( ) Gets the specified El ement property for the current 

selection. 

document . get El ementTextAttr( ) Gets a specif ied TextAttrs property of the selected text 

objects. 

document . get Sel ecti onRect( ) Gets the bounding rectangle of the current selection, 

document . getTextStri ng ( ) Gets the currently selected text. 

document . getTi mel i ne( ) Retrieves the current Timeline object in the document. 

document . getTransf ormati onPoi nt( ) Gets the location of the transformation point of the 

current selection. 

document . group ( ) Converts the current selection to a group. 

document . importPubl i shProf i 1 e( ) Imports a profile from a file. 

document, import SWF ( ) Imports a SWF file into the document. 

document, match ( ) Makes the size of the selected objects the same. 

document .moused i ck( ) Performs a mouse click from the arrow tool. 

document .mo us eDbl CI k ( ) Performs a double mouse click from the arrow tool. 

document .mo veSel ectedBezi erPoi ntsBy ( ) If the selection contains at least one path with at least 

one Bezier point selected, this method moves all 
selected Bezier points on all selected paths by the 
specified amount. 

document. moveSel ecti onBy ( ) Moves selected objects by aspecified distance. 

document . opt i mi zeCurves( ) Optimizes smoothing for the current selection, allowing 

multiple passes, if specified, for optimal smoothing; 
equivalent to selecting Modify > Shape > Optimize. 

document . pub 1 i sh( ) Publishes the document according to the active Publish 

Settings (see File > Publish Settings); equivalent to 
selecting File > Publish. 

document. removeDataFromDocumentt ) Removes persistent data with the specified name that 

has been attached to the document. 

document . removeDataFromSel ecti on ( ) Removes persistent data with the specified name that 

has been attached to the selection. 

document . renamePubl i shProf i 1 e( ) Renames the current profile. 

document. renameScene( ) Renames the currently selected scene in the Scenes 

panel. 

document . reo rder Scene ( ) Moves the specified scene before another specified 

scene. 

document. resetTransf ormati on ( ) Resets the transformation matrix; equivalent to selecting 

Modify > Transform > Remove transform. 

document . revert ( ) Reverts the specified document to its previously saved 

version; equivalent to selecting File > Revert. 
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Method 



Description 



document. rotateSelectiont) 
document . save ( ) 

document. saveAndCompact( ) 

document. seal eSelect ion O 

document . sel ectAl 1 ( ) 

document .selectNoneO 
document. setAl ignTo Document () 



document. setCustomFillO 

document . setCustomStroket ) 

document. setEl ement Property ( ) 

document . set El erne nt Text At t r ( ) 

document. setFillCo1or( ) 

document .setlnstanceAlphaO 
document. setlnstanceBrightnessO 
document. setlnstanceTintO 
document .setSelectionBounds() 
document .setSelectionRectO 

document. setStrokeO 
document.setStrokeColor() 

document. setStrokeSizeO 

document .setStrokeStyle() 

document. setTextRectangle() 



Rotates the selection by a specified amount. 

Saves the document in its default location; equivalent to 
selecting File > Save. 

Saves and compacts the file; equivalent to selecting 
File > Save and Compact. 

Scales the selection by a specified amount; equivalent to 
using the Free Transform tool to scale the object. 

Selects all items on the Stage; equivalent to pressing 
Control+A (Windows) or Command+A (Macintosh) or 
selecting Edit > Select All. 

Deselects any selected items. 

Sets the preferences for document . al ign( ), 
document .distributee ), document. mat ch( ), and 
document . space( ) to act on the document; equivalent to 
enabling the To Stage button in the Align panel. 

Sets the fill settings for the toolbar, Property inspector, 
and any selected shapes. 

Sets the stroke settings for the toolbar, Property 
inspector, and any selected shapes. 

Sets the specified Element property on selected 
object(s) in the document. 

Sets the specified TextAttrs property of the selected 
text items to the specified value. 

Changes the fill color of the selection to the specified 
color. 

Sets the opacity of the instance. 
Sets the brightness for the instance. 
Sets the tint for the instance. 

Moves and resizes the selection in a single operation. 

Draws a rectangular selection marquee relative to the 
Stage, using the specified coordinates. 

Sets the color, width, and style of the selected strokes. 

Changes the stroke color of the selection to the specified 
color. 

Changes the stroke size of the selection to the specified 
size. 

Changes the stroke style of the selection to the specified 
style. 

Changes the bounding rectangle for the selected text 
item to the specified size. 
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Method Description 



document 


setTextSel ecti on ( ) 


Sets the text selection of the currently selected text field 
to the values specified by the start Index and endlndex 
values. 


document 


setTextStri ng ( ) 


Inserts a string of text. 


document 


setTransformationPointt) 


Moves the transformation point of the current selection. 


document 


. skewSel ecti on ( ) 


Skews the selection by a specified amount. 


document 


. smoothSel ecti on ( ) 


Smooths the curve of each selected fill outline or curved 
line. 


document 


.space( ) 


Spaces the objects in the selection evenly. 


document 


straightenSelectiont ) 


Straightens the currently selected strokes; equivalent to 
using the Straighten button in the Tools panel. 


document 


swapEl ement( ) 


Swaps the current selection with the specified one. 


document 


testMovi e( ) 


Executes a Test Movie operation on the document. 


document 


testScenet ) 


Executes a Test Scene operation on the current scene of 
the document. 


document 


,traceBitmap( ) 


Performs a trace bitmap on the current selection; 
equivalent to selecting Modify > Bitmap > Trace Bitmap. 


document 


transforms el ecti on ( ) 


Performs a general transformation on the current 
selection by applying the matrix specified in the 
arguments. 


document 


unGroup( ) 


Ungroups the current selection. 


document 


unl ockAl 1 El ements ( ) 


Unlocks all locked elements on the currently selected 
frame. 


document 


.xml Panel ( ) 


Posts a XMLUI dialog box. 



Property summary for the Document object 

You can use the following properties with the Document object. 

Property Description 



document .accName A string that is equivalent to the Name field in the 

Accessibility panel. 

document . auto Label A Boolean value that is equivalent to the Auto Label 

check box in the Accessibility panel. 

document . backgroundCol or A color in hexidecimal format that represents the 

background color. 

document . currentPubl i shProf i 1 e A string that specifies the name of the active publish 

profile for the specified document. 

document . cur rentTimel ine An integer that specifies the index of the active Timeline. 
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Property Description 



document 


descri pti on 


A string that is equivalent to the Description field in the 
Accessibility panel. 


document 


, f orceSi mpl e 


A Boolean value that specifies whether the children of 
the specified object are accessible. 


document 


. f rameRate 


A float value that specifies the number of frames 
displayed per second when the SWF file plays; the 
default is 12. 


document 


. hei ght 


An integer that specifies the height of the document 
(Stage) in pixels. 


document 


1 i brary 


|—\ 1 1 .1 1 - 1 1 I 

Read-only; the library ob|ect for a document. 


document 


1 i vePrevi ew 


A Boolean value that specifies if Live Preview is enabled. 


document 


.name 


Read-only; a string that represents the name of a 
document (FLA file). 


document 


path 


Read-only; a string that represents the path of the 
document. 


document 


publ i shProf i 1 es 


Read-only; an array of the publish profile names for the 
document. 


document 


. screenOutl i ne 


Read-only; the current ScreenOutline object for the 
document. 


document 


sel ecti on 


An array of the selected objects in the document. 


document 


si 1 ent 


A Boolean value that specifies whether the object is 
accessible. 


document 


, time! i nes 


Read-only; an array of Timeline objects (see Timeline 
object). 


document 


, vi ewMat ri x 


Read-only; a Matrix object. 


document 


.width 


An integer that specifies the width of the document 
(Stage) in pixels. 



document.accName 

Availability 

Flash MX 2004. 

Usage 

document . accName 

Description 

Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers 
identify objects by reading the name aloud. 
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Example 

The following example sets the accessibility name of the document to " M a i n Movie": 

f 1 . getDocumentDOMt ) . accName = "Main Movie"; 

The following example gets the accessibility name of the document: 

fl .tracetfl .getDocumentDOMt ) .accName) ; 

document.addDataToDocument() 

Availability 

Flash MX 2004. 
Usage 

document . addDataToDocument ( name, type, data ) 
Parameters 

name A string that specifies the name of the data to add. 

type A string that defines the type of data to add. The valid values for type are "integer", 
" i nteger Array ", "double", "doubl eArray ", "string", and "byteArray ". 

data the value to add. Valid types depend on the type parameter. 
Returns 

Nothing. 
Description 

Method; stores specified data with a document. Data is written to the FLA file and is available to 
JavaScript when the file reopens. See document . getData FromDocument ( ) and 
document . removeData FromDocument ( ). 

Example 

The following example adds an integer value of 12 to the current document: 

f 1 . getDocumentDOMt ) . addDataf oDocumentt "my Data " , "integer", 12 ) ; 

The following example returns the value of the data named "my Data " and displays the result in 
the Output panel: 

fl .tracetfl . getDocumentDOMt ) . getData FromDocument ( "my Data " ) ) ; 

document.addDataToSelection() 

Availability 

Flash MX 2004. 
Usage 

document . addDatafoSel ecti on ( name, type, data ) 
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Parameters 

name A string that specifies the name of the persistent data. 

type Defines the type of data. The valid values for type are: "integer", "i ntegerArray ", 
"doubl e", "doubl eArray ", "string", and "byteArray ". 

data the value to add. Valid types depend on the type parameter. 
Returns 

Nothing. 
Description 

Method; stores specified data with the selected object(s). Data is written to the FLA file and is 
available to JavaScript when the file reopens. Only symbols and bitmaps support persistent data. 

See document . removeDataFromSel ecti on ( ). 

Example 

The following example adds an integer value of 12 to the selected object: 

f 1 . get Document DOM ( ).addDataToSelection("myData", "integer", 12); 

document.addltem() 

Availability 

Flash MX 2004. 
Usage 

document . addltem( position, item ) 
Parameters 

pos i ti on A point that specifies the xnndy coordinates of the location at which to add the 
item. It uses the center of a symbol or the upper left corner of a bitmap or video. 

item An Item object that specifies the item to add and the library from which to add it. 
Returns 

A Boolean value: true if successful; false otherwise. 
Description 

Method; adds an item from any open document or library to the specified Document object. 
Example 

The following example adds the first item from the library to the first document at the specified 
location for the selected symbol, bitmap, or video: 

var item = fl . documents [0] . 1 i brary . i terns [0] ; 
fl.documents[0].addltem(jx:0,y:0), it em); 
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The following example adds the symbol myMovi eCl i p from the current document's library to the 
current document: 

var itemlndex = fl . getDocumentDOM( ). 1 i brary . fi ndlteml ndex( "myMovi eCl i p" ) ; 
var theltem = fl . getDocumentDOMt ). 1 i brary . i terns [ i teml ndex] ; 
fl .get Document DOM ( ) .addltem( {x:0,y :0) , theltem) ; 

The following example adds the symbol myMov i eCl i p from the second document in the 
documents array to the third document in the documents array: 

var itemlndex = fl . documents [1] . 1 i brary . fi ndlteml ndex( "myMovi eCl i p" ) ; 
var theltem = fl . documents [1] . 1 i brary . i terns [i temlndex] ; 
fl.documents[2].addltem(jx:0,y:0), theltem); 

document.addNewLine() 

Availability 

Flash MX 2004. 
Usage 

document . addNewLi ne ( startPoi nt, endpoi nt ) 
Parameters 

startpoi nt A pair of floating point numbers that specify the x and y coordinates where the line 
starts. 

endpo int A pair of floating point numbers that specify the x and y coordinates where the line 
ends. 

Returns 

Nothing. 
Description 

Method; adds a new path between two points. The method uses the document's current stroke 
attributes and adds the path on the current frame and current layer. This method works in the 
same way as clicking on the line tool and drawing a line. 

Example 

The following example adds a line between the specified starting point and ending point: 

fl .getDocumentDOM( ) .addNewLine( { x : 216 . 7 , y : 122 . 3 } , |x:366.8, y:165.8|); 

document.addNewOval() 

Availability 

Flash MX 2004. 
Usage 

document . addNewOval ( boundi ngRectangl e [ , bSuppressFi 1 1 [ , bSuppressStroke ]] ) 
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Parameters 

boundi ngRectangl e A rectangle that specifies the bounds of the oval to be added. 

bSuppressFi 7 7 A Boolean value that, if set to true, causes the method to create the shape 
without a fill. The default value is false. This parameter is optional. 

bSuppressStroke A Boolean value that, if set to true, causes the method to create the shape 
without a stroke. The default value is f al se . This parameter is optional. 

Returns 

Nothing. 
Description 

Method; adds a new oval in the specified bounding rectangle. This method performs the same 
operation as the oval tool. The method uses the document's current default stroke and fill 
attributes and adds the oval on the current frame and layer. If bSurpressFi 1 1 is set to true, the 
oval is drawn without a fill. If bSurpressStroke is set to true, the oval is drawn without a 
stroke. If both bSuppressFi 1 1 or bSuppressStroke are set to true, the method will do nothing. 

Example 

The following example adds a new oval within the specified coordinates: 

flash.getDocumentDOM( ) .addNewOval ( { 1 ef t : 72 , top : 50 , ri ght : 236 , bottom : 228 I ) ; 
The following example draws an oval without fill: 

flash.getDocumentDOM( ) .addNewOval ({ 1 eft : 72 , top : 50 , ri ght : 236 , bottom : 228 1 , 
true ) ; 

The following example draws an oval without stroke: 

flash.getDocumentDOM( ) .addNewOval ( { 1 ef t : 72 , top : 50 , ri ght : 236 , bottom : 228 I , 
false, true); 

document.addNewPublishProfile() 

Availability 

Flash MX 2004. 
Usage 

document . addNewPubl i shProfi 1 e ( [profileNaine ] ) 
Parameters 

profi 1 eName the unique name of the new profile. If you do not specify a name, a default name 
is provided. This parameter is optional. 

Returns 

An integer that is the index of the new profile in the profiles list. Returns -1 if a new profile 
cannot be created. 
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Description 

Method; adds a new publish profile and makes it the current one. See 

document .deletePublishProfilet). 

Example 

The following example adds a new publish profile with a default name and then displays the 
name of the profile in the Output panel: 

fl .get Document DOM ( ) .addNewPubl ishProf i 1 e( ) ; 

fl .outputPanel . trace ( fl . get Document DOM ( ) .currentPubl ishProfile) ; 
The following example adds a new publish profile with the name "my prof i 1 e": 
f 1 . getDocumentDOMt ).addNewPublishProfile("my profile"); 

document.addNewRectangle() 

Availability 

Flash MX 2004. 
Usage 

document . addNewRectangl e ( boundi ngRectangl e , roundness 
[, bSuppressFi 1 1 [ , bSuppressStroke ] ] ) 

Parameters 

boundi ngRectangl e A rectangle that specifies the bounds within which the new rectangle is 
added. This parameter specifies a pixel location for 1 eft, top, ri ght, and bottom. 

roundness An integer value between 0 and 999 that specifies the roundness to use for the 
corners. The value is specified as number of points. The greater the value, the greater the 
roundness. 

bSuppressFi 1 7 A Boolean value that, if set to true, causes the method to create the shape 
without a fill. The default value is f al se. This parameter is optional. 

bSuppressStroke A Boolean value that, if set to true, causes the method to create the 
rectangle without a stroke. The default value is false. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; adds a new rectangle or rounded rectangle, fitting it into the specified bounds. This 
method performs the same operation as the rectangle tool. The method uses the document's 
current default stroke and fill attributes and adds the rectangle on the current frame and layer. If 
the bSuppressFi 1 1 parameter is set to true, the rectangle is drawn without a fill. If the 
bSuppressStroke parameter is set to true, the rectangle is drawn without a stroke. Either 
bSuppressFi 1 1 or bSuppressStroke must be set to fal se or the method does nothing. 
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Example 

The following example adds a new rectangle with no round corners within the specified 
coordinates. 

fl ash .get Document DOM ( ) . addNewRectangl e ( j 1 ef t : 0 , top : 0 , ri ght : 100 , bottom : 100 ) ,0) ; 

The following example adds a new rectangle with no round corners and without a fill. 

f 1 ash. get Document DOM ( ) .addNewRectangl e( { 1 eft : 0 , top : 0 , ri ght : 100 , bottom : 100 } ,0, 
true ) ; 

The following example add a new rectangle no round corners and without a stroke. 

f 1 ash. get Document DOM ( ) .addNewRectangl e( { 1 eft : 0 , top : 0 , ri ght : 100 , bottom : 100 } ,0, 
fal se, true) ; 

document.addNewScene() 

Availability 

Flash MX 2004. 
Usage 

document . addNewScene ( [name] ) 
Parameters 

name Specifies the name of the scene. If you do not specify a name, a new scene name is 
generated. 

Returns 

A Boolean value: true if the scene is added successfully; f al se otherwise. 
Description 

Method; adds a new scene (Ti mel i ne object) as the next scene after the currently selected scene 
and makes the new scene the currently selected scene. If the specified scene name already exists, 
the scene is not added and the method returns an error. 

Example 

The following example adds a new scene named my Scene after the current scene in the current 
document. The variable success will be true when the new scene is created; false otherwise 

var success = f 1 ash . getDocumentD0M( ) . addNewScene( "myScene" ) ; 

The following example adds a new scene using the default naming convention. If only one scene 
exists, the newly created scene is named "Scene 2 " . 

fl . getDocumentD0M( ) . addNewScene ( ) ; 
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document.addNewText() 

Availability 

Flash MX 2004. 
Usage 

document . addNewText ( boundi ngRectangl e ) 
Parameters 

bound i ngRectang 1 e Specifies the size and location of the text field by providing locations in 
pixels for 1 eft, top, ri grit, and bottom. The method applies the current text attributes. It 
should be followed by calling setTextStringt) to populate the new text box. 

Returns 

Nothing. 
Description 

Method; inserts a new empty text field. See document . setTextStri ng( ). 
Example 

The following example creates a new text field in the upper left corner of the Stage and then sets 
the text string to "Hel 1 o Worl d": 

fl .getDocumentDOM( ) .addNewTexU {left:0, top:0, right:100, bottom : 100 }) ; 
fl .get Document DOM ( ) . setTextStri ng( 'Hello Worl d! ' ) ; 

document.align() 

Availability 

Flash MX 2004. 
Usage 

document. al ign( alignmode [, bUseDocumentBounds ] ) 
Parameters 

a 1 ignmode A string that specifies how to align the selection. Valid values for a 1 ignmode are 
"left", "right", "top", "bottom", "vertical center", and "horizontal center". 

bUseDocumentBounds A Boolean value that, if set to true, causes the method to align to the 
bounds of the document. Otherwise, the method uses the bounds of the selected objects. The 
default is fal se. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; aligns the selection. See document . di stri bute( ), 

document . setAl i gnToDocument ( ), and document . getAl ignToDocument( ). 
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Example 

The following example aligns objects to left and to the Stage. This is equivalent to turning on the 
To Stage setting in the Align panel and clicking the Align to Left button: 

f 1 . get Document DOM ( ) . al i gn ( " 1 ef t " , true ) ; 

document.allowScreens() 

Availability 

Flash MX 2004. 
Usage 

document .allowScreensO 
Parameters 

None. 
Returns 

Returns a Boolean value: trueifdom.screenOutline can be used safely; f a 1 se otherwise. 
Description 

Method; Used before using the document . screenOutl i ne property. If this method returns the 
value true, you can safely access the screenOutl i ne property. Flash displays an error if you 
access the screenOutl ine property in a document without screens. 

Example 

The following example determines whether screens methods can be used in the current 
document: 

i f ( f 1 . get Document DOM ( ).allowScreens()) { 
fl . tracet "screen outline is available."); 

I 

else ( 

fl . tracet "whoops , no screens."); 

} 

document.arrange() 

Availability 

Flash MX 2004. 
Usage 

document. arrange( arrangeMode ) 
Parameters 

arrangeMode Specifies the direction in which to move the selection. The valid values for 
arrangemode are "back", "backward", "forward", and "front". It provides the same 
capabilities as these options provide on the Modify >Arrange menu. 
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Returns 

Nothing. 
Description 

Method; arranges the selection on the Stage. This method applies only to non-shape objects. 
Example 

The following example moves the current selection to the front: 

f 1 . getDocumentDOM( ).arrange(" front"); 

document.autoLabel 

Availability 

Flash MX 2004. 

Usage 

document . autoLabel 

Description 

Property; A Boolean value that is equivalent to the Auto Label check box in the Accessibility 
panel. You can use this property to tell Flash to automatically label objects on the Stage with the 
text associated with them. 

Example 

The following example gets the value of the autoLabel property and displays the result in the 
Output panel: 

var isAutoLabel = fl . getDocumentDOM( ). autoLabel ; 
fl . trace ( is AutoLabel ) ; 

The following example sets the autoLabel property to true, telling Flash to automatically label 
objects on the Stage: 

fl . getDocumentDOM( ). autoLabel = true; 

document. backgroundColor 
Availability 

Flash MX 2004. 
Usage 

document . backgroundColor 
Description 

Property; a color in hexidecimal format that represents the background color. 
Example 

The following example sets the background color to black: 

fl .getDocumentDOM( ) .backgroundColor = '#000000'; 
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document.breakApart() 

Availability 

Flash MX 2004. 

Usage 

document. breakApartt ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; performs a break-apart operation on the current selection. 
Example 

The following example breaks apart the current selection: 

fl . get Document DOM ( ) .breakApartt ) ; 

document.canEditSymbolO 

Availability 

Flash MX 2004. 
Usage 

document . canEdi t Symbol ( ) 
Parameters 

None. 
Returns 

A Boolean value: true if the Edit Symbols menu and functionality are available for use; f al se 
otherwise. 

Description 

Method; indicates whether the Edit Symbols menu and functionality are enabled. This is not 
related to whether the selection can be edited. This method should not be used to test whether 
f 1 . getDocumentDOM( ) . enterEdi tMode( ) is allowed. 

Example 

The following example displays in the Output panel the state of the Edit Symbols menu and 
functionality: 

fl . trace( "fl . getDocumentDOM( ). canEdi tSymbol ( ) returns: " + 
fl .getDocumentDOMt ) .canEdi tSymbol ( ) ) ; 
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document.canRevert() 

Availability 

Flash MX 2004. 

Usage 

document . canRevert ( ) 

Parameters 

None. 
Returns 

A Boolean value: true if you can use the document . revert () or fl . reve rt Document ( ) 
methods successfully; f al se otherwise. 

Description 

Method; determines whether you can use the document .revertOorfl. revert Document ( ) 
method successfully. 

Example 

The following example checks whether the current document can revert to the previously saved 
version. If so, fl .getDocumentDOMt ) .revertt ) restores the previously saved version. 

if (fl . get Document DOM ( ).canRevert()){ 
f 1 . getDocumentDOMt ). revert () ; 

} 

document.canTestMovie() 

Availability 

Flash MX 2004. 
Usage 

document . canfestMovi e ( ) 
Parameters 

None. 
Returns 

A Boolean value: true if you can use the document . testMovi e( ) method successfully: false 
otherwise. 

Description 

Method; determines whether you can use the document. testMovi e( ) method successfully. See 

document. canTestScenet ) and document . testScene( ). 
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Example 

The following example tests whether f 1 . ge t Document DOM ( ) . testMovi e( ) can be used. If so, it 
calls the method. 

if (fl . get Document DOM ( ).canTestMovie()){ 
fl . get Document DOM ( ) .testMovi e( ) ; 

} 

document.canTestScene() 

Availability 

Flash MX 2004. 
Usage 

document . canTestScene ( ) 
Parameters 

None. 
Returns 

A Boolean value: true if you can use the document . testScene( ) method successfully; false 
otherwise. 

Description 

Method; determines whether you can use the document . testScene ( ) method successfully. See 

document . canfestMovi e ( ) and document . testMovi e( ). 

Example 

The following example first tests whether f 1 . ge t Document DOM ( ). testScene ( ) can be used 
successfully. If so, it calls the method. 

if (fl . get Document DOM ( ).canfestScene()){ 
f 1 . ge t Document DOM ( ).testScene(); 

} 

document.clipCopy() 

Availability 

Flash MX 2004. 

Usage 

document . cl i pCopy ( ) 

Parameters 

None. 
Returns 

Nothing. 
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Description 

Method; copies the current selection from the document to the Clipboard. 
Example 

The following example copies the current selection from the document to the Clipboard: 

fl . get Document DOM ( ) . cl i pCopy ( ) ; 

document. clipCut() 

Availability 

Flash MX 2004. 

Usage 

document . cl i pCut ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; cuts the current selection from the document and writes it to the Clipboard. 
Example 

The following example cuts the current selection from the document and writes it to the 
Clipboard: 

fl .getDocumentDOM( ) .cl ipCut( ) ; 

document.clipPaste() 

Availability 

Flash MX 2004. 
Usage 

document . cl i pPaste ( [blnPl ace] ) 
Parameters 

blnPl ace A Boolean value that, when set to true, causes the method to perform a paste-in- 
place operation. The default value is f al se, which causes the method to perform a paste 
operation to the center of the document. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; pastes the contents of the Clipboard into the document. 
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Example 

The following examples pastes the Clipboard contents to the center of the document: 

fl . get Document DOM ( ) . cl i pPaste( ) ; 

The following example pastes the Clipboard contents in place in the current document: 

fl . get Document DOM ( ).clipPaste(true); 

document.close() 

Availability 

Flash MX 2004. 
Usage 

document . cl ose ( [bProinptToSaveChanges] ) 
Parameters 

bPromptToSaveChanges A Boolean value that, when set to true, causes the method to prompt 
the user with a dialog box if there are unsaved changes in the document. If 
bPromptToSa veChanges is set to false, the user is not prompted to save any changed 
documents. The default value is true. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; closes the specified document. 
Example 

The following example closes the current document and prompts the user with a dialog box to 
save changes: 

f 1 . get Document DOM ( ) . cl ose ( ) ; 

The following example closes the current document without saving changes: 

f 1 . get Document DOM ( ).close(false); 

document.convertl_inesToFills() 

Availability 

Flash MX 2004. 

Usage 

document .convertLinesfoFillst) 
Parameters 
None. 
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Returns 

Nothing. 
Description 

Method; converts lines to fills on the selected objects. 
Example 

The following example converts the current selected lines to fills: 

f 1 . getDocumentDOM( ) .convertLinesToFi 1 1 s ( ) ; 

document.convertToSymbol() 

Availability 

Flash MX 2004. 
Usage 

document . convertToSymbol ( type, name, regi strati onPoi nt ) 
Parameters 

type A string that specifies the type of symbol to create. Valid values for type are "movi e 
clip", "button", and "graphic". 

name A string that specifies the name for the new symbol, which must be unique. You can 
submit an empty string to have this method create a unique symbol name for you. 

regi strati on point Specifies the point that represents the 0,0 location for the symbol. 
Acceptable values are: "top left", "top center", "top ri ght", "center 1 eft", "center", 
"center ri ght", "bottom 1 eft", "bottom center", and "bottom right". 

Returns 

An object for the newly created symbol, or nul 1 if it cannot create the symbol. 
Description 

Method; converts the selected Stage item(s) to a new symbol. For information on defining linkage 
and shared asset properties for a symbol, see Item object. 

Example 

The following examples create a movie clip symbol with a specified name, a button symbol with a 
specified name, and a movie clip symbol with a default name: 

newMc = f 1 . getDocumentDOM( ) . convertf oSymbol ( "movi e clip", "mcSymbol Name" , "top 
left"); 

newButton = fl .getDocumentDOMt ) . convertf oSymbol ( "button" , "btnSymbol Name" , 
"bottom ri ght" ) ; 

newCl i pWi thDef aul tName = f 1 . getDocumentDOMt ) . convertf oSymbol ( "movi e clip", 
"top 1 eft" ) ; 
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document.currentPublishProfile 

Availability 

Flash MX 2004. 
Usage 

document .currentPublishProfile 
Description 

Property; a string that specifies the name of the active publish profile for the specified document. 
Example 

The following example adds a new publish profile with the default name and then displays the 
name of the profile in the Output panel: 

fl .get Document DOM ( ) . addNewPubl ishProf i 1 e( ) ; 

fl .outputPanel . trace ( fl . get Document DOM ( ) .currentPubl ishProfile) ; 
The following example changes the selected publish profile to "Default": 
fl . getDocumentDOMt ). currentPubl i shProfi 1 e = "Default"; 

document.currentTimeline 

Availability 

Flash MX 2004. 
Usage 

document . currentfimel ine 
Description 

Property; an integer that specifies the index of the active Timeline. You can set the active Timeline 
by changing the value of this property; the effect is almost equivalent to calling 
document.editScenet ). The only difference is that you don't get an error message if the index of 
the Timeline is not valid (the property is simply not set, which causes silent failure). 

See document . getfi mel ine( ). 
Example 

The following example displays the index of the current Timeline. 

var myCurrentfL = f 1 . getDocumentDOM( ) . currentf i mel i ne ; 

f 1 . trace( "T he index of the current timeline is: "+ myCurrentfL); 

The following example changes the active Timeline from the main Timeline to a scene named 
"myScene". 

var i = 0 ; 

var curfimelines = f 1 . getDocumentDOM( ) . ti mel i nes ; 
while(i < f 1 . getDocumentDOM( ) . timel i nes . 1 ength ) { 
i f( curfi mel i nes [ i ]. name == "myScene"){ 
fl . getDocumentDOM( ). currentf imel i ne = i; 
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++i ; 

} 

document.deletePublishProfile() 

Availability 

Flash MX 2004. 
Usage 

document .deletePublishProfilet ) 
Parameters 

None. 
Returns 

An integer that is the index of the new current profile. If a new profile is not available, the method 
leaves the current profile unchanged and returns its index. 

Description 

Method; deletes the currently active profile, if there is more than one. There must be at least one 
profile left. See document . addNewPubl i shProf i 1 e( ). 

Example 

The following example deletes the currently active profile, if there is more than one, and displays 
the index of the new currently active profile: 

ale rt(fl. get Document DOM O.deletePublishProfileO); 

document.deleteScene() 

Availability 

Flash MX 2004. 
Usage 

document . del eteScene ( ) 
Parameters 

None. 
Returns 

A Boolean value: true if the scene is successfully deleted; f al se otherwise. 
Description 

Method; deletes the current scene (Timeline object) and, if the deleted scene was not the last one, 
sets the next scene as the current Timeline object. If the deleted scene was the last one, it sets the 
first object as the current Timeline object. If only one Ti mel i ne object (scene) exists, it returns 
the value f al se . 
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Example 

Assuming there are three scenes (SceneO, Scenel, and Scene2) in the current document, the 
following example makes Scene2 the current scene and then deletes it: 

fl .get Document DOM ( ) . edi tScene ( 2 ) ; 

var success = f 1 . getDocumentDOMt ) . del eteScene( ) ; 

document.deleteSelection() 

Availability 

Flash MX 2004. 
Usage 

document .deleteSelectionU 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; deletes the current selection on the Stage. Displays an error message if there is no 
selection. 

Example 

The following example deletes the current selection in the document: 

f 1 . getDocumentDOMt ).deleteSelection(); 

document.description 

Availability 

Flash MX 2004. 

Usage 

document . descri pti on 

Description 

Property; a string that is equivalent to the Description field in the Accessibility panel. The 
description is read by the screen reader. 

Example 

The following example sets the description of the document: 

fl . getDocumentDOMt ). descri pti on= "This is the main movie"; 

The following example gets the description of the document and displays it in the Output panel: 

fl . t racet f 1 . getDocumentDOMt ). description); 
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document. distribute() 

Availability 

Flash MX 2004. 
Usage 

document . di stri bute ( di stri butemode [, bUseDocumentBounds ] ) 
Parameters 

di stri butemode A string that specifies where to distribute the selected object. Valid values for 

di stri buteMode are "1 eft edge", "horizontal center", " ri ght edge", "top edge", 
"vertical center", and "bottom edge". 

bUseDocumentBounds A Boolean value that, when set to true, distributes the selected objects 
using the bounds of the document. Otherwise, the method uses the bounds of the selected object. 
The default is f al se. 

Returns 

Nothing. 

Description 

Method; distributes the selection. See document . setAl i gnToDocument ( ) and 
document . getAl i gnToDocument ( ). 

Example 

The following example distributes the selected objects by the top edge: 

f 1 . getDocumentDOM( ). distributer' top edge"); 

The following example distributes the selected objects by top edge and expressly sets the 
bUseDcoumentBounds parameter: 

fl . getDocumentDOM( ) .distribute( "top edge", false); 

The following example distributes the selected objects by their top edges, using the bounds of the 
document: 

fl . getDocumentDOMt ) .distributet "top edge", true); 

document.distributeTol_ayers() 

Availability 

Flash MX 2004. 
Usage 

document. di stri buteToLayers ( ) 
Parameters 
None. 
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Returns 

Nothing. 
Description 

Method; performs a distribute-to-layers operation on the current selection — equivalent to 
selecting Distribute to Layers. This method displays an error if there is no selection. 

Example 

The following example distributes the current selection to layers: 

fl . getDocumentDOM( ) .distributeToLayers( ) ; 

document.documentHasData() 

Availability 

Flash MX 2004. 
Usage 

document . documentHasData ( name ) 
Parameters 

name A string that specifies the name of the data to check. 
Returns 

A Boolean value: true if the document has persistent data; f al se otherwise. 
Description 

Method; checks the document for persistent data with the specified name. See 

document . addDataToDocument ( ), document. getDataFromDocument( ), and 
document . remove Data FromDocument ( ). 

Example 

The following example checks the document for persistent data with the name "my Data " : 
var hasData = fl . getDocumentDOM( ) . documentHasData ( "myData" ) ; 

document.duplicatePublishProfileQ 

Availability 

Flash MX 2004. 
Usage 

document . dupl i catePubl i shProfi 1 e( [profi 1 eName ] ) 
Parameters 

profi leHame Astring that specifies the unique name of the duplicated profile. If you do not 
specify a name, the method uses the default name. This parameter is optional. 
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Returns 

An integer that is the index of the new profile in the profile list. Returns -1 if the profile cannot 
be duplicated. 

Description 

Method; duplicates the currently active profile and gives the duplicate version focus. 
Example 

The following example duplicates the currently active profile and displays the index of the new 
profile in the Output panel: 

fl . t race( f 1 . get Document DOM ( ).duplicatePublishProfile("dup profile")); 

document.duplicateScene() 

Availability 

Flash MX 2004. 
Usage 

document . dupl icateScenet) 
Parameters 

None. 
Returns 

A Boolean value: true if the scene is duplicated successfully; false otherwise. 
Description 

Method; makes a copy of the currently selected scene, giving the new scene a unique name and 
making it the current scene. 

Example 

The following example duplicates the second scene in the current document: 

f 1 . getDocumentDOM( ) . edi tScene ( 1 ) ; //set the middle scene to current scene 
var success = f 1 . getDocumentDOMt ) . dupl i cateScene( ) ; 

document.duplicateSelection() 

Availability 

Flash MX 2004. 
Usage 

document .duplicateSelectionU 
Parameters 
None. 
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Returns 

Nothing. 
Description 

Method; duplicates the selection on the Stage. 
Example 

The following example duplicates the current selection, which is similar to Alt-clicking and then 
dragging an item: 

fl . get Document DOM ( ).duplicateSelection(); 

document.editScene() 

Availability 

Flash MX 2004. 
Usage 

document . edi tScene ( index ) 
Parameters 

index A zero-based integer that specifies which scene to edit. 
Returns 

Nothing. 
Description 

Method; makes the specified scene the currently selected scene for editing. 
Example 

Assuming that there are three scenes (SceneO, Scenel, and Scene2) in the current document, the 
following example makes Scene2 the current scene and then deletes it: 

fl .getDocumentDOM( ) . edi tScene ( 2 ) ; 
f 1 . get Document DOM ( ).deleteScene(); 

document.enterEditMode() 

Availability 

Flash MX 2004. 
Usage 

document . enterEdi tMode ( [edi tMode~\ ) 
Parameters 

edi tMode A string that specifies the editing mode. Valid values are " i n PI a ce " or 

"newWi ndow". If no parameter is specified, the default is symbol-editing mode. This parameter is 

optional. 
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Returns 

Nothing. 
Description 

Method; switches the authoring tool into the editing mode specified by the parameter. If no 
parameter is specified, the method defaults to symbol-editing mode, which has the same result as 
right-clicking the symbol to invoke the context menu and selecting Edit. See 

document.exitEditMode( ). 

Example 

The following example puts Flash in edit-in-place mode for the currently selected symbol: 

f 1 . g et Document DOM ( ). enter Ed itMode('inPlace'); 

The following example puts Flash in edit-in-new- window mode for the currently selected symbol: 

f 1 . get Document DOM ( ) .enter Ed itMode( ' newWi ndow ' ) ; 

document.exitEditMode() 

Availability 

Flash MX 2004. 
Usage 

document . exi tEdi tMode( ) 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; exits from symbol-editing mode and returns focus to the next level up from the editing 
mode. For example, if you are editing a symbol inside another symbol, this method takes you up 
a level from the symbol you are editing, into the parent symbol. See 

document . enterEdi tMode ( ). 

Example 

The following example exits symbol-editing mode: 
fl .get Document DOM ( ). exi tEdi tMode ( ) ; 

document. exportPublishProfile() 

Availability 

Flash MX 2004. 
Usage 

document . exportPubl i shProfi 1 e ( fileURI ) 
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Parameters 

f 7 leURI A string, expressed as a file: //URL, that specifies the path of the XML file to which the 
profile is exported. 

Returns 

Nothing. 
Description 

Method; exports the currently active profile to a file. 
Example 

The following example exports the currently active profile to the file named profile.xml in the 
folder /Documents and Settings/username/Desktop on the C drive: 

f 1 . get Document DOM ( ).exportPublishProfile('file:///C| /Documents and Settings/ 
userna me /Desktop/prof ile.xml'); 

document.exportSWF() 

Availability 

Flash MX 2004. 
Usage 

document . exportSWF( [fileURI]{, bCurrentSetti ngs] ) 
Parameters 

fileURI A string, expressed as a file://URL, that specifies the name of the exported file. If 
f / 1 eURI is empty or not specified, Flash displays the Export Movie dialog box. This parameter is 
optional. 

bCurrentSetti ngs A Boolean value that, when set to true, causes Flash to use current SWF 
publish settings. Otherwise, Flash displays the Export Flash Player dialog box. The default is 
fal se. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; exports the document to the specified file in the Flash SWF format. 
Example 

The following example exports the document to the specified file location with the current 
publish settings: 

f 1 . ge t Document DOM ( ) . export SWF( "fi 1 e : ///C | /Documents and Settings/gdrieu/ 
Desktop/qwerty . swf " ) ; 
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The following example displays the Export Movie dialog box and the Export Flash Player dialog 
box and then exports the document based on the specified settings: 

f 1 . getDocumentDOM( J.exportSWFC", true); 

The following example displays the Export Movie dialog box and then exports the document with 
specified settings: 

fl .getDocumentDOM( ) .exportSWFt ) ; 

document.forceSimple 

Availability 

Flash MX 2004. 

Usage 

document . f orceSimpl e 

Description 

Property; a Boolean value that specifies whether the children of the specified object are accessible. 
This is equivalent to the inverse logic of the Make Child Objects Accessible setting in the 
Accessibility panel. That is, if f orceSi mpl e is true, it is the same as the Make Child Object 
Accessible option being unchecked . If forceSimpl e is fal se, it is the same as the Make Child 
Object Accessible option being checked. 

Example 

The following example sets the areChildrenAccessible variable to the value of the 
forceSimpl e property; a value of f al se means the children are accessible: 

var areChildrenAccessible = f 1 . getDocumentDOM( ) . f orceSi mpl e ; 

The following example sets the f orceSi mpl e property to allow the children of the document to 
be accessible: 

fl . getDocumentDOM( ). forceSimpl e = false; 

document.frameRate 

Availability 

Flash MX 2004. 

Usage 

document . f rameRate 

Description 

Property; a float value that specifies the number of frames displayed per second when the SWF 
file plays; the default is 12. This is the same functionality as setting the frame rate in the 
Document properties dialog box (Modify > Document). 
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Example 

The following example sets the frame rate to 25.5 frames per second: 
f 1 . getDocumentDOM( ) . f rameRate = 25.5; 

document.getAlignToDocument() 

Availability 

Flash MX 2004. 
Usage 

document . getAl i gnToDocument ( ) 
Parameters 

None. 
Returns 

A Boolean value: true if the preference is set to align the objects to the Stage; f al se otherwise. 
Description 

Method; identical to retrieving the value of the To Stage button in the Align panel. Gets the 
preference that can be used for document, alignt), document .distributee ), 
document .match ( ), and document . space ( ) methods on the document. See 
document. setAl i gnToDocument ( ). 

Example 

The following example retrieves the value of the To Stage button in the Align panel. If the return 
value is true, the To Stage button is active; otherwise, it is not. 

var isAlignToDoc = fl . getDocumentDOM( ) .getAl i gnToDocument( ) ; 
f 1 . get Document DOM ( ) . al i gn ( " 1 ef t " , i sAl i gnToDoc ) ; 

document.getCustomFill() 

Availability 

Flash MX 2004. 
Usage 

document . getCustomFi 1 1 ( [ objectToFill ] ) 
Parameters 

objectToFi 1 1 A string that specifies the location of the fill object. The following values are 
valid: 

• "toolbar", which returns the fill object of the toolbar and Property inspector 

• "selection", which returns the fill obj ect of the selection 

If you omit this parameter, the default value is "selection". If there is no selection, the method 
returns undefined. This parameter is optional. 
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Returns 

The Fill object specified by the objectToFi 1 1 parameter, if successful; otherwise, it returns 

undef i ned . 

Description 

Method; retrieves the fill object of the selected shape or, if specified, of the toolbar and Property 
inspector. See document . setCustomFi 1 1 ( ). 

Example 

The following example gets the fill object of the selection and then changes the selection's color to 
white: 

var fill = f 1 . getDocumentDOM( ) . getCustomFi 1 1 ( ) ; 
fill .color = 1 #FFFFFF 1 ; 
fill, styl e = "solid"; 

fl .get Document DOM () .setCustomFi 1 1 (fi 1 1 ) ; 

The following example returns the fill object of the toolbar and Property inspector and then 
changes the color swatch to a linear gradient: 

var fill = fl . getDocumentDOM( ). getCustomFi 1 1 ( "tool bar" ) ; 
fill. style = "1 i nearGradi ent" ; 

fill .colorArray = [ OxOOffOO, OxffOOOO, OxOOOOff ]; 

fi 1 1 .posArray = [0 , 100 , 200] ; 

fl .getDocumentDOMt ) .setCustomFi 1 1 ( fill ); 

document.getCustomStrokeQ 

Availability 

Flash MX 2004. 
Usage 

document . getCustomStroke ( [ 1 ocati onOf Stroked ) 
Parameters 

7 ocati on Of Stroke A string that specifies the location of the stroke object. The following values 
are valid: 

• "toolbar", which, if set, returns the stroke object of the toolbar and Property inspector. 

• "sel ecti on", which, if set, returns the stroke object of the selection. 

If you omit this parameter, it defaults to " sel ecti on ". If there is no selection, it returns 
undef i ned. This parameter is optional. 

Returns 

The Stroke object specified by the 1 ocati onOf Stroke parameter, if successful; otherwise, it 
returns undef i ned. 
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Description 

Returns the stroke object of the selected shape or, if specified, of the toolbar and Property 
inspector. See document . setCustomStroke( ). 

Example 

The following example returns the current stroke settings of the selection and changes the stroke 
thickness to 2: 

var stroke = f 1 . getDocumentDOMt ) . getCustomStroke( "sel ecti on " ) ; 
stroke . thi ckness = 2; 

fl .getDocumentDOMt ) . setCustomStroke( stroke) ; 

The following example returns the current stroke settings of the toolbar and Property inspector 
and sets the stroke color to red: 

var stroke = fl .getDocumentDOMt ) .getCustomStroket "tool bar" ) ; 
stroke. color = "#FF0000"; 

fl .getDocumentDOMt ) . setCustomStroket stroke) ; 

document.getDataFromDocument() 

Availability 

Flash MX 2004. 
Usage 

document. getDataFromDocumentt name ) 
Parameters 

name A string that specifies the name of the data to return. 
Returns 

The specified data. 
Description 

Method; retrieves the value of the specified data. The type returned depends on the type of data 
that was stored. See document . addDataf o Document ( ), document . document Has Data ( ), and 
document . remove Data FromDocument ( ). 

Example 

The following example adds an integer value of 12 to the current document and uses this method 
to display the value in the Output panel: 

f 1 . getDocumentDOMt ) . addDataf oDocumentt "my Data " , "integer", 12 ) ; 
fl .tracetfl . getDocumentDOMt ) . getDataFromDocumentt "my Data " ) ) ; 
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document.getElementPropertyO 

Availability 

Flash MX 2004. 
Usage 

document . getEl ementProperty ( propertyName ) 
Parameters 

The name of the Element property for which to retrieve the value. 
Returns 

The value of the specified property. Returns null if the property is an indeterminate state, as 
when multiple elements are selected with different property values. Returns undef i ned if the 
property is not a valid property of the selected element. 

Description 

Method; gets the specified El ement property for the current selection. See "Property summary for 
the Element object" on page 149 for a list of valid values. See 

document. set El ementProperty ( ). 

Example 

The following example gets the name of the Element property for the current selection: 

//el ementName = the instance name of the selected object 

var elementName = fl . getDocumentDOM( ). getEl ementProperty ( "name" ) ; 

document.getElementTextAttr() 

Availability 

Flash MX 2004. 
Usage 

document . getEl ementTextAttr ( attrNamel, startlndex [, end Index]] ) 
Parameters 

attrName A string that specifies the name of the TextAttrs property to be returned. For a list 
of property names and expected values, see "Property summary for the TextAttrs object" 
on page 299. 

sta rtlndex An integer that specifies the index of first character, with 0 (zero) specifying the 
first position. This parameter is optional. 

endlndex An integer that specifies the index of last character. This parameter is optional. 
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Returns 

If one text field is selected, the property is returned if there is only one value used within the text. 
Returns undefined if there are several values used inside the text field. If several text fields are 
selected, and all the text alignment values are equal, the method returns this value. If several text 
fields are selected, but all the text alignment values are not equal, the method returns undefined. 
If the optional arguments are not passed, these rules apply to the range of text currently selected 
or the whole text field if the text is not currently being edited. If only startlndex is passed, the 
property of the character to the right of the index is returned, if all the selected text objects match 
values. If startlndex and endlndex are passed, the value returned reflects the entire range of 
characters from startlndex up to, but not including, endlndex. 

Description 

Method; gets a specific Text Att rs property of the selected text objects. Selected objects that are 
not text fields are ignored. For a list of property names and expected values, see "Property 
summary for the TextAttrs object" on page 299. See document . setEl ementTextAttrt ). 

Example 

The following example gets the size of the selected text fields: 
f 1 . get Document DOM ( ) . get El ementTextAttr( "si ze" ) ; 

The following example gets the color of the character at index 3 in the selected text fields: 
f 1 . get Document DOM ( ) . get El erne nt Text At tr ( "f i 1 1 Col or " , 3 ) ; 

The following example gets the font name of the text from index 2 up to, but not including, 
index 10 of the selected text fields: 

f 1 . getDocumentDOMt ) . get El ementTextAttr ( "f ace" , 2, 10); 



document.getSelectionRect() 

Availability 

Flash MX 2004. 
Usage 

document . getSel ecti onRect ( ) 
Parameters 

None. 
Returns 

The bounding rectangle of the current selection, or 0 if nothing is selected. 
Description 

Method; gets the bounding rectangle of the current selection. If a selection is non-rectangular, the 
smallest rectangle encompassing the entire selection is returned. The rectangle is based on the 
document space or, when in an edit mode, the registration point of the symbol being edited. See 

document . setSel ecti onRect ( ). 
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Example 

The following example gets the bounding rectangle for the current selection and then displays its 
properties: 

var newRect = f 1 . getDocumentDOM( ) . getSel ecti onRect ( ) ; 

var outputStr = "left: " + newRect . 1 ef t + " top: " + newRect.top + " right: " + 

newRect . ri ght + " bottom: " + newRect . bottom; 
alert (outputStr ) ; 

document.getTextString() 

Availability 

Flash MX 2004. 
Usage 

document . getTextStri ng ( [startlndex [, endlndex^^ ) 
Parameters 

s tartlndex An integer that is an index of first character to get. This parameter is optional. 
end Index An integer that is an index of last character to get. This parameter is optional. 
Returns 

A string that contains the selected text. 
Description 

Method; gets the currently selected text. If the optional parameters are not passed, the current text 
selection is used. If text is not currently opened for editing, the whole text string is returned. If 
only startlndex is passed, the string starting at that index and ending at the end of the field is 
returned. If startlndex and endlndex are passed, the string starting from startlndex up to, 
but not including, endlndex is returned. See document . setTextStri ng ( ). 

If there are several text fields selected, the concatenation of all the strings is returned. 
Example 

The following example gets the string in the selected text fields: 

f 1 . get Document DOM ( ).getTextString(); 

The following example gets the string at character index 5 in the selected text fields: 

fl . getDocumentDOMt ) .getTextString(5) ; 

The following example gets the string from character index 2 up to, but not including, character 
index 10: 

fl .get Document DOM ( ) . getf extStri ng( 2 , 10) ; 
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document.getTimeline() 

Availability 

Flash MX 2004. 
Usage 

document . getTimel ine( ) 
Parameters 

None. 
Returns 

The current Timeline object. 
Description 

Method; retrieves the current Timeline object in the document. The current Timeline can be the 
current scene, the current symbol being edited, or the current screen. See 

document . currentTimel i ne, document . ti mel i nes, and symbol Item . ti mel i ne. 

Example 

The following example gets the Timeline object and returns the number of frames in the longest 
layer: 

var longestLayer = fl . getDocumentDOM( ). getTimel i ne( ). frameCount ; 
f 1 . tracet "The longest layer has" + longestLayer + "frames"); 

The following example enters edit-in-place mode for the selected symbol on the Stage and inserts 
a frame on the symbol's Timeline. 

f 1 . g et Document DOM ( ). enter Ed itMode("inPlace"); 

f 1 . getDocumentDOM( ) .getTimel ine( ) .insertFrames( ) ; 

The following example gets the Timeline object and displays its name: 

var timeline = f 1 . getDocumentDOM( ) . getTi mel i ne( ) ; 
al ert ( timel i ne . name ) ; 

document.getTransformationPointO 

Availability 

Flash MX 2004. 
Usage 

document . getTransf ormati onPoi nt ( ) 
Parameters 

None. 
Returns 

The location of the transformation point. 
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Description 

Method; gets the location of the transformation point of the current selection. You can use the 
transformation point for commutations such as rotate and skew. See 

document . setTransf ormati onPoi nt ( ). 

Example 

The following example gets the transformation point for the current selection. The 
transPoint.x property gives the x coordinate of the transformation point. The transPoint.y 
property gives thej coordinate of the transformation point: 

var transPoint = fl . getDocumentDOM( ) .getTransformationPoint( ) ; 

document.group() 

Availability 

Flash MX 2004. 

Usage 

document . group( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; converts the current selection to a group. See document . unGroup( ). 
Example 

The following example converts the objects in the current selection to a group: 

f 1 . get Document DOM ( ) . group( ) ; 

document.height 

Availability 

Flash MX 2004. 

Usage 

document . hei ght 

Description 

Property; an integer that specifies the height of the document (Stage) in pixels. See 
document. width. 
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Example 

The following example sets the height of the Stage to 400 pixels: 

fl .getDocumentDOM( ) .height = 400; 

document.importPublishProfile() 

Availability 

Flash MX 2004. 
Usage 

document . importPubl i shProfi 1 e ( fileURI ) 
Parameters 

f 7 leURI A string that specifies the path, expressed as a file://URL, of the XML file defining the 
profile to import. 

Returns 

An integer that is the index of the imported profile in the profiles list. Returns -1 if the profile 
cannot be imported. 

Description 

Method; imports a profile from a file. 
Example 

The following example imports the profile contained in the profile.xml file and displays its index 
in the profiles list: 

al ert ( f 1 . ge t Document DOM ( ) . importPubl ishProfile( ' f i 1 e : ///C | /Documents and 
Setti ngs/ use rname/ Desktop/prof i 1 e.xml ')) ; 

document.importSWF() 

Availability 

Flash MX 2004. 
Usage 

document. importSWF( fileURI ) 
Parameters 

f 7 leURI A string that specifies the URI, expressed as a file://URI, for the SWF file to import. 
Returns 

Nothing. 
Description 

Method; imports a SWF file into the document. Performs the same operation as using the Import 
menu option to specify a SWF file. 
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Example 

The following example imports the "mySwf . swf " file from the Flash Configuration folder: 

f 1 . get Document DOM ( ) . importSWF(f 1 .conf i gURI+"mySwf .swf " ) ; 

document.library 

Availability 

Flash MX 2004. 

Usage 

document . 1 i brary 

Description 

Read-only property; the library object for a document. 
Example 

The following example gets the library for the currently focused document: 

var myCurrentLib = fl . getDocumentDOM( ). 1 i brary ; 

Assuming the currently focused document is not fl .documents[l], the following example gets 
the library for a non-focused library or for a library you opened using File > Open as external 
library: 

var externalLib = f 1 . documents [ 1] . 1 i brary ; 

document.livePreview 

Availability 

Flash MX 2004. 

Usage 

document . 1 i vePrevi ew 

Description 

Property; a Boolean value that specifies if Live Preview is enabled. If set to true, components 
appear on the Stage as they will appear in the published Flash content, including their 
approximate size. If set to f al se, components appear only as outlines. The default value is true. 

Example 

The following example sets Live Preview to f al se: 

f 1 . getDocumentDOM( ) . 1 i vePrevi ew = false; 
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document.match() 

Availability 

Flash MX 2004. 
Usage 

document . match ( bUidth, bHeight [, bUseDocumentBounds] ) 
Parameters 

bhlidth A Boolean value that, when set to true, causes the method to make the widths of the 
selected items the same. 

bHeight A Boolean value that, when set to true, causes the method to make the heights of the 
selected items the same. 

bUseDocumentBounds A Boolean value that, when set to true, causes the method to match the 
size of the objects to the bounds of the document. Otherwise, the method uses the bounds of the 
largest object. The default is false. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; makes the size of the selected objects the same. See document . setAl i gnToDocument ( ) 
and document . getAl i gnToDocument ( ). 

Example 

The following example matches the width of the selected objects only: 

f 1 . get Document DOM ( ). ma ten (true, false); 
The following example matches the height only: 

f 1 . getDocumentDOMt ) .match(false.true) ; 

The following example matches the width only to the bounds of the document: 

fl .getDocumentDOMt ) .match(true,fal se.true) ; 

document.mouseClick() 

Availability 

Flash MX 2004. 
Usage 

document, moused ick( posi ti on, bToggl eSel , bShi ftSel ) 
Parameters 

position A pair of floating point values that specify the x and y coordinates of the click in 
pixels. 
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bToggl eSel A Boolean value that specifies the state of the Shift key: true for pressed; false 
for not pressed. 

bSh i ftSel A Boolean value that specifies the state of the application preference Shift select: 
true for on; f al se for off. 

Returns 

Nothing. 
Description 

Method; performs a mouse click from the arrow tool. See document .mouseDbl CI k( ). 
Example 

The following example performs a mouse click at the specified location: 

fl .getDocumentDOM( ) .moused ick( jx:300, y:2001, false, false); 

document.mouseDblClk() 

Availability 

Flash MX 2004. 
Usage 

document . mouseDbl CI k( position, bAHDown, bShi ftDown, bShi ftSel ect ) 
Parameters 

position A pair of floating point values that specify the x and y coordinates of the click in 
pixels. 

bA 1 tdown A Boolean value that records whether the At key is down at the time of the event: 
true for pressed; f al se for not pressed. 

bSh i ftDown A Boolean value that records whether the Shift key was down when the event 
occurred: true for pressed; fal se for not pressed. 

bShi ftSel ect A Boolean value that indicates the state of the application preference Shift 
select: true for on; f al se for off. 

Returns 

Nothing. 
Description 

Method; performs a double mouse click from the arrow tool. See document, moused ick( ). 
Example 

The following example performs a double mouse click at the specified location: 

fl .getDocumentDOMt ) .mouseDbl CI k( |x:392. 9, y:73), false, false, true); 
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document.moveSelectedBezierPointsByO 

Availability 

Flash MX 2004. 
Usage 

document . moveSel ectedBezi erPoi ntsBy( delta ) 
Parameters 

del ta A pair of floating point values that specify the x Andy coordinates in pixels by which the 
selected Bezier points are moved. For example, passing ( { x : 1 , y : 2 ) ) specifies a location that is to 
the right by one pixel and down by two pixels from the current location. 

Returns 

Nothing. 
Description 

Method; if the selection contains at least one path with at least one Bezier point selected, moves 
all selected Bezier points on all selected paths by the specified amount. 

Example 

The following example moves the selected Bezier points 10 pixels to the right and 5 pixels down: 

f 1 . getDocumentDOM( ) .moveSelectedBezierPointsBy( { x : 10 , y : 5) ) ; 

document.moveSelectionByO 

Availability 

Flash MX 2004. 
Usage 

document . moveSel ecti onBy ( di stanceToMove ) 
Parameters 

di stanceToMove A pair of floating point values that specify the x and y coordinate values by 
which the method moves the selection. For example, passing ({x : 1 , y : 2}) specifies a location one 
pixel to the right and two pixels down from the current location. 

Returns 

Nothing. 
Description 

Method; moves selected objects by a specified distance. 

Note: When using arrow keys to move the item, the History panel combines all presses of the arrow 
key as one move step. When the user presses the arrow keys repeatedly, rather than taking multiple 
steps in the History panel, the method performs one step, and the arguments are updated to reflect 
the repeated arrow keys. 



102 Chapter 3: Objects 



For information on making a selection, see document . setSel ecti onRectt ), 
document . moused i ck( ), document .mouseDblCl k( ), and the Element object. 

Example 

The following example moves the selected item 62 pixels to the right and 84 pixels down: 

flash. get Document DOM ( ).moveSelectionBy({x:62, y:84}); 

document.name 

Availability 

Flash MX 2004. 

Usage 

document . name 

Description 

Read-only property; a string that represents the name of a document (FLA file). 
Example 

The following example sets the variable f i 1 eName to the filename of the first document in the 
documents array: 

var fileName = fl ash . documents [0] . name ; 

The following example displays the names of all the open documents in the Output panel: 

var openDocs = fl . documents ; 

for(var i=0;i < opendocs . 1 ength ; i++)( 

fl. traced + " " + opendocs [i ]. name +"\n"); 

} 

document.optimizeCurves() 

Availability 

Flash MX 2004. 
Usage 

document . optimi zeCurves ( smoothi ng, bUseMul ti pi ePasses ) 
Parameters 

smoothi ng An integer in the range from 0 to 100, with 0 specifying no smoothing, and 100 
specifying maximum smoothing. 

bUseMu 1 ti pi ePasses A Boolean value that, when set to true, indicates that the method 
should use multiple passes, which is slower but produces a better result. This parameter has the 
same effect as clicking the Use multiple passes button in the Optimize Curves dialog box. 

Returns 

Nothing. 



Document object 103 



Description 

Method; optimizes smoothing for the current selection, allowing multiple passes, if specified, for 
optimal smoothing. This method is equivalent to selecting Modify > Shape > Optimize. 

Example 

The following example optimizes the curve of the current selection to 50° of smoothing with 
multiple passes: 

fl . getDocumentDOM( ) .optimizeCurves(50, true) ; 

document.path 

Availability 

Flash MX 2004. 

Usage 

document .path 

Description 

Read-only property; a string that represents the path of the document. If the document has never 
been saved, this property is undefined. 

Example 

The following example displays the path of the first document in the documents array in the 
Output panel: 

var filePath = fl ash . documents [0] . path ; 
fl .trace(filePath) ; 

document.publish() 

Availability 

Flash MX 2004. 

Usage 

document . publ ish( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; publishes the document according to the active Publish Settings (see File > Publish 
Settings). This method is equivalent to selecting File > Publish. 
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Example 

The following example publishes the current document: 

fl . get Document DOM ( ) . publ ish( ) ; 

document.publishProfiles 

Availability 

Flash MX 2004. 
Usage 

document .publishProfiles 
Description 

Read-only property; an array of the publish profile names for the document. 
Example 

The following example displays the names of the publish profiles for the document: 

var my PubProf i 1 es = f 1 . getDocumentDOM( ) . publ i shProf i 1 es ; 
for (var i=0; i < my PubProf i 1 es . 1 ength ; i++)( 
fl . trace ( my PubProf i 1 es [i] ) ; 

} 

document.removeDataFromDocument() 

Availability 

Flash MX 2004. 
Usage 

document. removeDataFromDocumentt name ) 
Parameters 

name A string that specifies the name of the data to remove. 
Returns 

Nothing. 
Description 

Method; removes persistent data with the specified name that has been attached to the document. 

See document. addDataToDocument( ), document . getDataFromDocument( ), and 
document . documentHasData ( ). 

Example 

The following example removes from the document the persistent data named " my D a t a " : 

f 1 . getDocumentDOMt ) . removeDataFromDocumentt "my Data " ) ; 
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document.removeDataFromSelection() 

Availability 

Flash MX 2004. 
Usage 

document . removeDataFromSel ecti on( name ) 
Parameters 

name A string that specifies the name of the persistent data to remove. 
Returns 

Nothing. 
Description 

Method; removes persistent data with the specified name that has been attached to the selection. 

See document .addData To Select ion( ). 

Example 

The following example removes from the selection the persistent data named "my Data " : 
f 1 . getDocumentDOM( ) . removeDataFromSel ecti on ( "my Data ") ; 

document.renamePublishProfile() 

Availability 

Flash MX 2004. 
Usage 

document . renamePubl i shProfi 1 e ( [profileNewName ] ) 
Parameters 

profi 1 eNewName An optional parameter that specifies the new name for the profile. The new 
name must be unique. If the name is not specified, a default name is provided. 

Returns 

A Boolean value: true if the name is changed successfully; fal se otherwise. 
Description 

Method; renames the current profile. 
Example 

The following example renames the current profile to a default name and displays it: 

al ert ( f 1 . get Document DOM ( ) .renamePubl ishProfile( ) ) ; 
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document.renameScene() 

Availability 

Flash MX 2004. 
Usage 

document . renameScene ( name ) 
Parameters 

name A string that specifies the new name of the scene. 
Returns 

A Boolean value: true if the name is changed successfully; fal se otherwise. If the new name is 
not unique, for example, the method returns fal se. 

Description 

Method; renames the currently selected scene in the Scenes panel. The new name for the selected 
scene must be unique. 

Example 

The following example renames the current scene to "new name": 

var success = f 1 . getDocumentDOM( ) . renameScene( "new name"); 

document.reorderScene() 
Availability 

Flash MX 2004. 
Usage 

document . reorderScene ( sceneToMove, sceneToPutltBefore ) 
Parameters 

sceneToMove An integer that specifies which scene to move, with 0 (zero) being the first scene. 

sceneToPutltBefore An integer that specifies the scene before which you want to move the 
scene specified by sceneToMove. Specify 0 (zero) for the first scene. For example, if you specify 1 
for sceneToMove and 0 for sceneToPutltBefore, the second scene is placed before the first 
scene. Specify -1 to move the scene to the end. 

Returns 

Nothing. 
Description 

Method; moves the specified scene before another specified scene. 
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Example 

The following example moves the second scene to before the first scene: 

f 1 . get Document DOM ( ).reorderScene(l, 0); 

document.resetTransformation() 

Availability 

Flash MX 2004. 
Usage 

document . resetTransf ormati on ( ) 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; resets the transformation matrix. This method is equivalent to selecting Modify > 
Transform > Remove transform. 

Example 

The following example resets the transformation matrix for the current selection: 

f 1 . get Document DOM ( ) .resetTransformation( ) ; 

document. revert() 

Availability 

Flash MX 2004. 

Usage 

document . revert ( ) 

Parameters 

None. 
Returns 

Nothing. 

Description 

Method; reverts the specified document to its previously saved version. This method is equivalent 
to selecting File > Revert. See document .can Re vert ( ) and f 1 . r evert Document ( ). 
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Example 

The following example reverts the current document to the previously saved version: 

f 1 . get Document DOM ( ). revert () ; 

document.rotateSelection() 

Availability 

Flash MX 2004. 
Usage 

document . rotateSel ecti on ( angle [, rotati onPoi nt] ) 
Parameters 

angle A floating point value that specifies the angle of the rotation. 

rotati onPoi nt A string that specifies which side of the bounding box to rotate. Valid values 
are: "top right", "top 1 eft", "bottom ri ght", "bottom left", "top center", "right 
center", "bottom center", and "1 eft center". If unspecified, the method uses the 
transformation point. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; rotates the selection by a specified amount. The effect is the same as using the Free 
Transform tool to rotate the object. 

Example 

The following example rotates the selection by 45° around the transformation point: 

flash. g et Document DOM ( ) .rotateSelection(45) ; 

The following example rotates the selection by 45° around the lower left corner: 

fl . getDocumentDOM( ). rotateSel ecti on (45 , "bottom left"); 

document.save() 

Availability 

Flash MX 2004. 
Usage 

document . save ( [bOkToSaveAs] ) 
Parameters 

bOkToSa veAs An optional parameter that, if true or omitted, and the file was never saved, the 
Save As dialog box appears . If f a 1 s e and the file was never saved, the file is not saved. 
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Returns 

A Boolean value: true if the save operation completes successfully; f al se otherwise. 
Description 

Method; saves the document in its default location. This method is equivalent to selecting File > 
Save. See document . saveAndCompact ( ), f 1 . save Document As (),fl.saveDocument(), and 
fl .saveAl 1 ( ). 

Example 

The following example saves the current document in its default location: 

fl . get Document DOM ( ).save( ); 

document.saveAndCompact() 

Availability 

Flash MX 2004. 
Usage 

document. saveAndCompact( IbOkToSa veAs] ) 
Parameters 

bOkToSaveAs An optional parameter that, if true or omitted and the file was never saved, the 
Save As dialog box appears. If f a 1 se and the file was never saved, the file is not saved. 

Returns 

A Boolean value: true if the save-and-compact operation completes successfully; f al se 
otherwise. 

Description 

Method; saves and compacts the file. This method is equivalent to selecting File > Save and 
Compact. See document . save( ), f 1 . saveDocumentAs ( ), f 1 . saveDocument( ), and 
fl . saveAl 1 ( ). 

Example 

The following example saves and compacts the current document: 

fl . getDocumentDOM( ) . saveAndCompact( ) ; 

document.scaleSelection() 

Availability 

Flash MX 2004. 

Usage 

document . seal eSel ecti on ( xScale, yScale [, whichCorner^ ) 
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Parameters 

xScal e A floating point value that specifies the amount of x by which to scale. 

ySca 1 e A floating point value that specifies the amount of y by which to scale. 

wh i chCorner A string value that specifies the edge about which the transformation occurs. If 
omitted, scaling occurs about the transformation point. Acceptable values are: "bottom 1 eft", 
"bottom right", "top right", "top left", "top center", " ri ght center", "bottom 
center", and "left center". This parameter is optional. 

Returns 

Nothing. 
Description 

Method; scales the selection by a specified amount. This method is equivalent to using the Free 
Transform tool to scale the object. 

Example 

The following example expands the width of the current selection to double the original width 
and shrinks the height to half: 

flash. get Document DOM ( ).scaleSelection(2.0, 0.5); 
The following example flips the selection vertically: 
f 1 . get Document DOM ( ) .seal eSel ecti on(l , -1); 
The following example flips the selection horizontally: 

f 1 . get Document DOM ( ) .seal eSel ecti on( -1 , 1); 

The following example scales the selection vertically by 1.9 from the top center: 

fl . getDocumentDOMt ). seal eSel ecti on ( 1 , 1.90, 'top center'); 

document.screenOutline 

Availability 

Flash MX 2004. 
Usage 

document .screenOutline 
Description 

Read-only property; the current ScreenOutline object for the document. Before accessing the 
object for the first time, make sure to use document .all owScreens ( ) to determine whether the 
property exists. 

Example 

The following example displays the array of values in the screenOutl ine property: 

var myArray = new ArrayU; 

fortvar i in fl . getDocumentDOM( ). screenOutl i ne ) { 
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myArray .push( " : "+f 1 . getDocumentDOM( ) . screenOutl i ne[i ] ) ; 

I 

f 1 . trace( "Here is the property dump for screenOutl i ne : : "+myArray); 

document.selectAII() 

Availability 

Flash MX 2004. 

Usage 

document . sel ectAl 1 ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; selects all items on the Stage. This method is equivalent to pressing Control+A 
(Windows) or Command+A (Macintosh) or selecting Edit > Select All. See 

document .selectNonet ) and document .selection. 

Example 

The following example selects everything that is currently visible to the user: 

fl .get Document DOM () .sel ectAl 1 () ; 

document.selection 

Availability 

Flash MX 2004. 

Usage 

document .sel ecti on 

Description 

Property; an array of the selected objects in the document. If nothing is selected, returns an array 
of length zero. If no document is open, returns null. 

To add objects to the array, you must first select them in one of the following ways: 

• Manually select object(s) on the Stage. 

• Use one of the selection methods, such as document . setSel ecti onRect( ), 

document .setSelectionBoundst), document . moused i ck( ), document .mouseDblCl k( ), 
or document . sel ectAl 1 ( ). 

• Manually select a frame or frames. 
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• Use one of the methods of the Timeline object to select a frame or frames, such as 

timeline.getSelectedFrames(),timeline.setSelectedFrames(),or 
ti mel i ne . sel ectAl 1 Frames ( ). 

• Specify a particular element in a particular frame. For example, the following code specifies 
and selects an element: 

f 1 . getDocumentDOMt ) . getTimel i ne ( ) . 1 ayers [0] . frames [0] .el ements [0] ; 
Example 

The following example assigns all elements on Frame 1 1 to the current selection (remember that 
index values are different from frame number values): 

fl . getDocumentDOM( ) .getTimel ine( ) . currentFrame = 10; 
f 1 . getDocumentDOM( ) . sel ecti on = 

f 1 . getDocumentDOMt ). getTimel i net ). 1 ayers [0] .frames [10] .el ements ; 

The following example creates a rectangle in the upper left corner of the Stage and a text string 
underneath the rectangle. Then it selects both objects using document . setSel ecti onRect( ) 
and adds them to the document .sel ecti on array. Finally, it displays the contents of 
document .sel ecti on in the Output panel. 

fl .getDocumentDOMt ) . addNewRectangl e( (left:0, top:0, right:99, bottom:99), 0); 
fl .getDocumentDOMt ) .addNewTextt 11 eft : -1 , top:117.3, right:9.2, bottom : 134 . 6 }) ; 
f 1 . getDocumentDOMt J.setTextStringt'Hello Wo rid'); 

fl .getDocumentDOMt ) .set Sel ect ion Rectt { 1 eft : -28, top: -22, right : 156.0, 
bottom: 163 ) ) ; 

var theSel ecti onArray = fl . getDocumentDOMt ). sel ecti on ; 

fortvar i=0;i<tneSelectionArray.length;i++){ 

fl . tracet "fl . getDocumentDOMt ). sel ecti on [ "+i + " ] = " + theSel ecti onArray [ i ]) ; 

} 

The following example is an advanced example. It shows how to loop through the layer array and 
elements array to locate instances of a particular symbol and select them. You could extend this 
example to include loops for multiple frames or scenes. This example assigns all instances of the 
movie clip "myMovi eCl i p" in the first frame to the current selection: 

//assigns the layers array to the variable "theLayers" 
var theLayers = fl . getDocumentDOMt ). getTi mel i net ). 1 ayers ; 

//creates an array to hold all the elements that are instances of "myMovi eCl i p" 
var mySel ecti onArray = new Array; 

//counter variable 
var x=0 ; 

//begin loop through all the layers 
fortvar i=0; i < theLayers . 1 ength ; i++) { 

//gets the array of elements in frame 1 and assigns it to the array 
"the El ems" 

var theElems = theLayers [i ]. frames [0] . el ements ; 
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//begin loop through the elements on a layer 
fortvar c=0 ; c < theEl ems . 1 ength ; c++){ 

//checks to see if the element is of type "instance" 
i f( theEl ems [c] . el ementType == "instance")! 

//if the element is an instance, it checks if it is an instance of 
"myMovi eCl i p" 
i f( theEl ems [c] . 1 i brary I tern. name == "myMovi eCl i p" ) { 

//assigns elements that are instances of "myMovi eCl i p" to "mySel ecti onArray " 
mySel ecti onArray [x] = theEl ems [c] ; 

//increments counter variable 
x++; 

} 
I 

1 

} 



// Now that we have assigned all the instances of "myMovi eCl i p" 
// to "mySel ecti onArray " , we then set the document . sel ecti on array 
// equal to mySel ecti onArray . fhis selects the objects on stage, 
fl . getDocumentDOMt ). sel ecti on = mySel ecti onArray ; 

document.selectNone() 

Availability 

Flash MX 2004. 

Usage 

document .selectNone( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; deselects any selected items. See document . sel ecti on and document . sel ectAl 1 ( ). 
Example 

The following example deselects any items that are selected: 

f 1 . getDocumentDOMt ).selectNone(); 
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document.setAlignToDocumentQ 

Availability 

Flash MX 2004. 
Usage 

document . setAl i gnToDocument ( bToStage ) 
Parameters 

bToStage A Boolean value that, if set to true, aligns objects to the Stage. If set to f al se, it 
does not. 

Returns 

Nothing. 
Description 

Method; sets the preferences for document . al i gn ( ), document .distributee ), 

document .match ( ), and document . space ( ) to act on the document. This method is equivalent 

to enabling the To Stage button in the Align panel. See document . getAl i gnToDocument ( ). 

Example 

The following example enables the To Stage button in the Align panel to align objects with 
the Stage: 

fl . getDocumentDOM( ) .setAl i gnToDocument (true) ; 

document.setCustomFill() 

Availability 

Flash MX 2004. 
Usage 

document . setCustomFi 1 1 ( fill ) 
Parameters 

fill Sets the Fill object. 
Returns 

Nothing. 
Description 

Method; sets the fill settings for the toolbar, Property inspector, and any selected shapes. This 
allows a script to set the fill settings before drawing the object, rather than drawing the object, 
selecting it, and changing the fill settings. It also lets a script change the toolbar and Property 
inspector fill settings. See document . getCustomFi 1 1 ( ). 
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Example 

The following example changes the color of the fill color swatch in the toolbar, Property 
inspector, and any selected shapes to white: 

var fill = f 1 . getDocumentDOM( ) . getCustomFi 1 1 ( ) ; 
fill .color = ' # F F F F F F ' ; 
fill .style = "solid"; 

fl .get Document DOM ( ) .setCustomFi 1 1 (f i 1 1 ) ; 

document.setCustomStrokeQ 

Availability 

Flash MX 2004. 
Usage 

document . setCustomStroke ( stroke ) 
Parameters 

stroke A Stroke object. 
Returns 

Nothing. 
Description 

Method; sets the stroke settings for the toolbar, Property inspector, and any selected shapes. This 
allows a script to set the stroke settings before drawing the object, rather than drawing the object, 
selecting it, and changing the stroke settings. It also lets a script change the toolbar and Property 
inspector stroke settings. See document .getCustomStroke( ). 

Example 

The following example changes the stroke thickness setting in the toolbar, Property inspector, and 
any selected shapes: 

var stroke = fl .getDocumentDOMt ) .getCustomStroke( ) ; 
stroke. thickness += 2; 

fl .getDocumentDOMt ) .setCustomStroke (stroke) ; 

document.setElementProperty() 

Availability 

Flash MX 2004. 
Usage 

document . setEl ementProperty ( property, val ue ) 
Parameters 

property A string that specifies the name of the Element property to set. For a complete list of 
properties and values, see "Property summary for the Element object" on page 149. 
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Note: You can't use this method to set values for read-only properties, such as el ement . el ementType, 
el ement .top, and el ement . 1 ef t. 

va 1 ue Specifies the value to set in the specified Element property. 
Returns 

Nothing. 
Description 

Method; sets the specified El ement property on selected object(s) in the document. This method 
does nothing if there is no selection. 

Example 

The following example sets the width of all selected objects to 100 and the height to 50: 

f 1 . getDocumentDOMt ) . set El ement Property ( "width", 100 ) ; 
f 1 . getDocumentDOMt ) . set El ement Property ( "height", 50 ) ; 

document.setElementTextAttr() 

Availability 

Flash MX 2004. 
Usage 

document . setEl ementTextAttr ( attrName, attrValue [, startlndex [, endlndex~\~\ ) 
Parameters 

attrName A string that specifies the name of the TextAttrs property to change. 

attrVal ue The value to which to set the TextAttrs property. For a list of property names and 
expected values, see "Property summary for the TextAttrs object" on page 299. 

startlndex An integer value that specifies the index of the first character that is affected. This 
parameter is optional. 

endlndex An integer value that specifies the index of the last character that is affected. This 
parameter is optional. 

Returns 

A Boolean value: true if at least one text attribute property is changed; f al se otherwise. 
Description 

Method; sets the specified textAttrs property of the selected text items to the specified value. 
For a list of property names and allowable values, see "Property summary for the TextAttrs object" 
on page 299. If the optional parameters are not passed, the method sets the style of the currently 
selected text range, or the whole text field if no text is selected. If only startlndex is passed, the 
method sets that character's attributes. If startlndex and endlndex are passed, the method sets 
the attributes on the characters starting from startlndex up to, but not including, endlndex. If 
paragraph styles are specified, all the paragraphs that fall within the range are affected. 
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Example 

The following examples set the fi 1 1 Col or , italic, and bo 1 d text attributes for the selected 
text items: 

var success = f 1 . getDocumentDOM( ) . setEl ementf extAttr( "f i 1 1 Col or" , "#00ff00"); 
var pass = f 1 . getDocumentDOM( ) . setEl ementf extAttr ( " i tal i c" , true, 10); 
var ok = fl . getDocumentDOMt ). setEl ementf extAttrt "bol d" , true, 5, 15); 



document.setFillColor() 

Availability 

Flash MX 2004. 
Usage 

document . set Fi 1 1 Col or ( color ) 
Parameters 

col or A color string in hexadecimal #rrggbb format (where r is red, g is green, and b is blue), a 
hexidecimal color value (such as, OxffOOOO), or an integer color value. If set to null, no fill color 
is set, which is the same as setting the Fill color swatch in the user interface to no fill. 

Returns 

Nothing. 
Description 

Method; changes the fill color of the selection to the specified color. For information on changing 
the fill color in the toolbar and Property inspector, see document . setCustomFi 1 1 ( ). 

Example 

The first three statements in the following example set the fill color using each of the different 
formats for specifying color. The fourth statement sets the fill to no fill. 

fl a sh. get Document DOM ( ) .setFi 1 1 Col or( "#cc00cc" ) ; 
fl a sh. get Document DOM ( ) .setFi 1 1 Col or(OxccOOcc) ; 
fl ash. getDocumentDOMt ) .set Fi 1 1 Col or ( 120000 ) ; 
f 1 ash . getDocumentDOMt ).setFillColor(null); 



document.setlnstanceAlpha() 

Availability 

Flash MX 2004. 
Usage 

document . setlnstanceAl pha ( opacity ) 
Parameters 

opacity An integer between 0 (transparent) and 100 (completely saturated) that adjusts the 
transparency of the instance. 
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Returns 

Nothing. 
Description 

Methods; sets the opacity of the instance. 
Example 

The following example sets the opacity of the tint to a value of 50: 

fl . get Document DOM ( ) . setlnstanceAl pha(50) ; 

document.setlnstanceBrightness() 

Availability 

Flash MX 2004. 
Usage 

document . setlnstanceBri ghtness ( brightness ) 
Parameters 

brightness An integer that specifies brightness as a value from -100 (black) to 100 (white). 
Returns 

Nothing. 
Description 

Method; sets the brightness for the instance. 
Example 

The following example sets the brightness for the instance to a value of 50: 

fl . getDocumentD0M( ) .setInstanceBrightness(50) ; 

document.setlnstanceTint() 

Availability 

Flash MX 2004. 
Usage 

document. setlnstanceTinU col or, strength ) 
Parameters 

col or A color string in hexadecimal #rrggbb format (where r is red, g is green, and b is blue), a 
hexidecimal color value (such as, OxffOOOO), or an integer color value that specifies the color of the 
tint. This parameter is equivalent to picking the Color: Tint value for a symbol in the Property 
Inspector. 

strength An integer between 0 and 100 that specifies the opacity of the tint. 
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Returns 

Nothing. 
Description 

Method; sets the tint for the instance. 
Example 

The following example sets the tint for the selected instance to red with an opacity value of 50: 

fl .get Document DOM ( ) . set Ins tanceTi nt( Oxff 0000 , 50) ; 

document.setSelectionBounds() 

Availability 

Flash MX 2004. 
Usage 

document . setSel ecti onBounds ( boundi ngRectangl e ) 
Parameters 

boundi ngRectangl e A rectangle that specifies the new location and size of the selection. The 
parameter specifies location as left and top pixel locations and size as width and height. See 

document .setSelectionRectt ). 

Returns 

Nothing. 
Description 

Method; moves and resizes the selection in a single operation. 
Example 

The following example moves the current selection to 10, 20 and resizes it to 100, 200: 

var 1 = 10; 
var t = 20; 

fl .get Document DOM ( ) .set Select i onBounds ( {left :1 , top:t, right: (100+1 ) , 
bottom: (200+t) ) ) ; 

document.setSelectionRect() 

Availability 

Flash MX 2004. 

Usage 

document . setSel ecti onRect ( rect [, bRepl aceCurrentSel ecti on] ) 
Parameters 

rect A rectangle object to set as selected. 
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bRepl aceCurrentSel ecti on A Boolean value, that if set to true, replaces the current 
selection. If it is false, the method adds to the current selection. The default value, if not set, is 
true. 

Returns 

Nothing. 
Description 

Method; draws a rectangular selection marquee relative to the Stage, using the specified 
coordinates. This is unlike document . getSel ecti onRect( ), in which the rectangle is relative to 
the object being edited. 

This method is equivalent to dragging a rectangle with the arrow tool. An instance must be fully 
enclosed by the rectangle to be selected. 

Note: Repeating setSelectionRect() using the History panel or menu item repeats the step previous 
to the setSelectionRect() operation. 

See document .selection and document .setSelectionBounds( ). 
Example 

In the following example, the second selection replaces the first one: 

fl .getDocumentDOMt ) . setSel ecti onRect( (left:l, top:l, right:200, bottom : 200 1 ) ; 
fl .get Document DOM ( ) .set Select ion Rect( {left : 364.0, top: 203.0, right: 508.0, 
bottom:434.0) , true) ; 

In the following example, the second selection is added to the first selection. This is the same as 
the manual operation of holding down Shift and selecting a second object. 

fl .getDocumentD0M( ) . setSel ecti onRect( {leftrl, top:l, right:200, bottom : 200 }) ; 
fl .get Document DOM ( ) .set Select ion Rect( {left : 364.0, top: 203.0, right: 508.0, 
bottom:434.0) , false); 

document.setStrokeQ 

Availability 

Flash MX 2004. 
Usage 

document . setStroke ( col or, si ze, strokeType ) 
Parameters 

col or A color string in hexadecimal #rrggbb format (where r is red, g is green, and b is blue), a 
hexidecimal color value (such as, OxffOOOO), or an integer color value. 

size A floating point value that specifies the new stroke size for the selection. 

strokeType A string that specifies the new type of stroke for the selection. Valid values are 
"hairline", "solid", "dashed", "dotted", "ragged", "stipple", and "hatched". 
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Returns 

Nothing. 
Description 

Method; sets the color, width, and style of the selected strokes. For information on changing the 
stroke in the toolbar and Property inspector, see document . setCustomStroke( ). 

Example 

The following example sets the color of the stroke to red, the size to 3.25, and the type to dashed: 

f1.getDocumentD0M().setStroke("#ff0000", 3.25, "dashed"); 

document.setStrokeColor() 

Availability 

Flash MX 2004. 
Usage 

document . setStrokeCol or ( color ) 
Parameters 

col or A color string in hexadecimal #rrggbb format (where r is red, g is green, and b is blue), a 
hexidecimal color value (such as, OxffOOOO), or an integer color value. 

Returns 

Nothing. 
Description 

Method; changes the stroke color of the selection to the specified color. For information on 
changing the stroke in the toolbar and Property inspector, see document . setCustomStroke( ). 

Example 

The three statements in the following example set the stroke color using each of the different 
formats for specifying color: 

f 1 ash . get Document DOM ( ) . setStrokeCol or( "#cc00cc") ; 
flash. get Document DOM ( ) .setStrokeCol or (OxccOOcc) ; 
flash.getDocumentDOM( ) . setStrokeCol or ( 120000 ) ; 

document.setStrokeSize() 

Availability 

Flash MX 2004. 
Usage 

document . setStrokeSi ze ( size ) 
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Parameters 

s ize A floating point value from 0.25 to 10 that specifies the stroke size. The method ignores 
precision greater than two decimal places. 

Returns 

Nothing. 
Description 

Method; changes the stroke size of the selection to the specified size. For information on changing 
the stroke in the toolbar and Property inspector, see document . setCustomStroke ( ). 

Example 

The following example changes the stroke size for the selection to 5: 

fl . getDocumentDOMt ) .setStrokeSize(5) ; 

document.setStrokeStyle() 

Availability 

Flash MX 2004. 
Usage 

document . setStrokeSty 1 e ( strokeType ) 
Parameters 

strokeType A string that specifies the stroke style for the current selection. Valid values are 
"hairline", "solid", "dashed", "dotted", "ragged", "stipple", and "hatched". 

Returns 

Nothing. 
Description 

Method; changes the stroke style of the selection to the specified style. For information on 
changing the stroke in the toolbar and Property inspector, see document . setCustomStroke( ). 

Example 

The following example changes the stroke style for the selection to "dashed": 
f 1 . getDocumentDOM( ) .setStrokeStyle( "dashed") ; 

document.setTextRectangle() 

Availability 

Flash MX 2004. 
Usage 

document . setTextRectangl e ( boundi ngRectangl e ) 



Document object 123 



Parameters 

boundi ngRectangl e A text rectangle object that specifies the new size within which the text 
item should flow. 

Returns 

A Boolean value: true if the size of at least one text field is changed; f al se otherwise. 
Description 

Method; changes the bounding rectangle for the selected text item to the specified size. This 
method causes the text to reflow inside the new rectangle; the text item is not scaled or 
transformed. If the text is horizontal and static, the method takes into account only the width of 
the rectangle (the height is automatically computed to fit all the text). If the text is vertical, the 
method takes into account only the height of the rectangle (the width is automatically computed 
to fit all the text). If the text is dynamic or input, the method is limited by the width and height 
of the rectangle, but the text field is constrained to fit all the text. 

Example 

The following example changes the size of the bounding text rectangle to the specified 
dimensions: 

fl .getDocumentDOM( ) . setTextRectangl e( {left:0, top:0, right : 50 , bottom:200|) 

document.setTextSelection() 

Availability 

Flash MX 2004. 
Usage 

document . setTextSel ecti on ( startlndex, endlndex ) 
Parameters 

s tartlndex An integer that specifies the position of the first character to select. The first 
character position is 0 (zero). 

endlndex An integer that specifies the end position of the selection up to, but not including, 
endlndex. The first character position is 0 (zero). 

Returns 

A Boolean value: true if the method can successfully set the text selection; f al se otherwise. 
Description 

Method; sets the text selection of the currently selected text field to the values specified by the 
startlndex and endlndex values. Text editing is activated, if it isn't already. 

Example 

The following example selects the text from the 6th character through the 25th character: 

f 1 .document .setTextSelection(5, 25); 
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document.setTextStringO 

Availability 

Flash MX 2004. 
Usage 

document . setTextStri ng ( text [, startlndex [, endlndex^ ] ) 
Parameters 

text A string of the characters to insert in the text field. 

sta rtlndex An integer that specifies first character to replace. The first character position is 0 
(zero). This parameter is optional. 

endlndex An integer that specifies the last character to replace. The first character position is 0 
(zero). This parameter is optional. 

Returns 

A Boolean value: true if the text of at least one text string is set; f al se otherwise. 
Description 

Method; inserts a string of text. If the optional parameters are not passed, the existing text 
selection is replaced; if the text object isn't currently being edited, the whole text string is replaced. 
If only startlndex is passed, the string passed is inserted at this position. If startlndex and 
endlndex are passed, the string passed replaces the segment of text starting from s tartlndex up 
to, but not including, endlndex. See document . getTextStri ng( ). 

Example 

The following example replaces the current text selection with "Hello World": 

var success = fl . getDocumentDOM( ). setTextStri ng ( "Hel 1 o World!"); 

The following example inserts "hello" at position 6 of the current text selection: 

var pass = fl . getDocumentDOMt ). setTextStri ng( "hel 1 o" , 6); 

The following example inserts "Howdy" starting at position 2 and up to, but not including, 
position 7 of the current text selection: 

var ok = fl . getDocumentDOM( ). setTextStri ng( "Howdy " , 2, 7); 

document.setTransformationPointO 

Availability 

Flash MX 2004. 
Usage 

document. setTransformationPoint( trans format! onPoi nt ) 
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Parameters 

trans format! onPoi nt A pair of floating point numbers that specifies values for each of the 
following elements: 

• Shapes: trans forma ti onPoi nt is set relative to document. 0,0 is the same as the Stage (upper 
left corner). 

• Symbols: trans forma t ionPo int is set relative to the symbol's registration point. 0,0 is located 
at the registration point. 

• Text: trans formati onPoi nt is set relative to the text field. 0,0 is the upper left corner of 
text field. 

• Bitmaps/videos: trans formati onPoi nt is set relative to bitmap/video. 0,0 is the upper left 
corner of the bitmap or video. 

• Groups: trans formati onPoi nt is set relative to document. 0,0 is the same as the Stage (upper 
left corner) 

Returns 

Nothing. 
Description 

Method; moves the transformation point of the current selection. See 

document . ge tTr a ns formati onPoi nt ( ). 

Example 

The following example sets the transformation point of the current selection to 100, 200: 

f 1 . get Document DOM ( ) . setTransf ormati onPoi nt ( { x : 100 , y : 200 ) ) ; 

document.silent 

Availability 

Flash MX 2004. 

Usage 

document . si 1 ent 

Description 

Property; a Boolean value that specifies whether the object is accessible. This is equivalent to the 
inverse logic of the Make Movie Accessible setting in the Accessibility panel. That is, if 
document. s i 1 ent is true, it is the same as the Make Movie Accessible option being unchecked. 
If it is false, it is the same as the Make Movie Accessible option being checked. 

Example 

The following example sets the i sSi 1 ent variable to the value of the silent property: 
var isSilent = f 1 . getDocumentD0M( ) . si 1 ent ; 
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The following example sets the si 1 ent property to f al se, indicating that the document is 
accessible: 

f 1 . getDocumentDOM( ) . si 1 ent = false; 

document.skewSelection() 

Availability 

Flash MX 2004. 
Usage 

document . skewSel ecti on ( xSkew, ySkew [, whichEdge^ ) 
Parameters 

xSkew A floating point number that specifies the amount of x by which to skew, measured in 
degrees. 

ySkew A floating point number that specifies the amount of y by which to skew, measured in 
degrees. 

wh i chEdge A string that specifies the edge where the transformation occurs; if omitted, skew 
occurs at the transformation point. Valid values are: "top center", "right center", "bottom 
center", and "left center". This parameter is optional. 

Returns 

Nothing. 
Description 

Method; skews the selection by a specified amount. The effect is the same as using the Free 
Transform tool to skew the object. 

Example 

The following examples skew the selected object by 2.0 vertically and 1.5 horizontally. The 
second example transforms the object at the top center edge: 

flash. getDocumentDOMt ).skewSelection(2.0, 1.5); 

fl ash . getDocumentDOMt ). skewSel ecti on ( 2 . 0 , 1.5, "top center"); 

document.smoothSelection() 

Availability 

Flash MX 2004. 
Usage 

document . smoothSelectionU 
Parameters 
None. 
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Returns 

Nothing. 
Description 

Method; smooths the curve of each selected fill outline or curved line. This method performs the 
same action as the Smooth button in the Tools panel. 

Example 

The following example smooths the curve of the current selection: 

f 1 . getDocumentDOM( ) .smoothSelection( ) ; 

document.space() 

Availability 

Flash MX 2004. 
Usage 

document . space ( direction [, bUseDocumentBounds^ ) 
Parameters 

di rect ion A string that specifies the direction in which to space the objects in the selection. 
Valid values for direction are "horizontal " or "vertical " . 

bUseDocumentBounds A Boolean value that, when set to true , spaces the objects to the 
document bounds. Otherwise, the method uses the bounds of the selected objects. The default is 
f al se. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; spaces the objects in the selection evenly. See document . setAl i gnToDocument ( ) and 
document . get Al i gnToDocument ( ). 

Example 

The following example spaces the objects horizontally, relative to the Stage: 

fl . get Document DOM ( ).space(" horizontal", true); 

The following example spaces the objects horizontally, relative to each other: 

f 1 . get Document DOM ( ).space(" horizontal"); 

The following example spaces the objects horizontally, relative to each other, with 
bUseDcoumentBounds expressly set to fal se: 

fl . get Document DOM ( ). space(" horizontal", fal se); 
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document.straightenSelection() 

Availability 

Flash MX 2004. 
Usage 

document .straightenSelection( ) 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; straightens the currently selected strokes. This method is equivalent to using the 
Straighten button in the Tools panel. 

Example 

The following example straightens the curve of the current selection: 

f 1 . ge t Document DOM ( ) .straightenSel ection( ) ; 

document.swapElement() 

Availability 

Flash MX 2004. 
Usage 

document . swapEl ement ( name ) 
Parameters 

name A string that specifies the name of the library item to use. 
Returns 

Nothing. 
Description 

Method; swaps the current selection with the specified one. The selection must contain a graphic, 
button, movie clip, video, or bitmap. This method displays an error message if no object is 
selected or the given object could not be found. 

Example 

The following example swaps the current selection with Symbol 1 from the library: 

f 1 . getDocumentDOM( ) . swapEl ement ( ' Symbol 1 ' ) ; 
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document.testMovie() 

Availability 

Flash MX 2004. 

Usage 

document . testMovi e ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; executes a Test Movie operation on the document. See document. canTestMovie( ) and 
document . test Scene ( ). 

Example 

The following example tests the movie for the current document: 

f 1 . get Document DOM ( ) .testMovi e( ) ; 

document.testScene() 

Availability 

Flash MX 2004. 

Usage 

document . testScene ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; executes a Test Scene operation on the current scene of the document. See 

document . canTestScene ( ) and document . testMovi e( ). 

Example 

The following example tests the current scene in the document: 

f 1 . get Document DOM ( ).testScene(); 
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document.timelines 



Availability 

Flash MX 2004. 

Usage 

document. timel ines 

Description 

Read-only property; an array of Timeline objects (see Timeline object). See 

document. getTimel ine() and document . currentTi mel ine. 

Example 

The following example gets the array of current Timelines in the active document and displays 
their names in the Output panel: 

v a r i = 0 ; 

var curTimelines = f 1 . getDocumentDOM( ) . ti mel i nes ; 
whiled < fl . getDocumentDOM( ). timel i nes . 1 ength ) { 

al ert ( curTimel i nes [i ] . name ) ; 

++i ; 

} 

document.traceBitmapO 

Availability 

Flash MX 2004. 
Usage 

document . traceBi tmap( threshold, mini mumArea, curveFit, cornerThreshol d ) 
Parameters 

th res hoi d An integer that controls the number of colors in your traced bitmap. Valid values 
are integers between 0 and 500. 

mi ni mumArea An integer that specifies the radius measured in pixels. Valid values are integers 
between 1 and 1000. 

curveFit A string that specifies how smoothly outlines are drawn. Valid values are: "pixels", 
"very tight", "tight", "normal ", "smooth", and "very smooth". 

cornerFhreshol d A string that is similar to curveFi t, but it pertains to the corners of the 
bitmap image. Valid values are: "many corners", "normal ", and "few corners". 

Returns 

Nothing. 
Description 

Method; performs a trace bitmap on the current selection. This method is equivalent to selecting 
Modify > Bitmap > Trace Bitmap. 
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Example 

The following example traces the selected bitmap, using the specified parameters: 
fl .getDocumentDOMt ) .traceBitmaptO, 500, 'normal', 'normal'); 

document.transformSelection() 

Availability 

Flash MX 2004. 
Usage 

document . transformSel ecti on ( a, b, c, d) 
Parameters 

a A floating point number that specifies the (0,0) element of the transformation matrix. 

b A floating point number that specifies the (0,1) element of the transformation matrix. 

c A floating point number that specifies the (1,0) element of the transformation matrix. 

d A floating point number that specifies the (1,1) element of the transformation matrix. 
Returns 

Nothing. 
Description 

Method; performs a general transformation on the current selection by applying the matrix 
specified in the arguments. For more information, see the el ement .matri x property. 

Example 

The following example stretches the selection by a factor of 2 in the x direction: 

fl .getDocumentDOMt ) . transformSel ecti on ( 2 . 0 , 0.0, 0.0, 1.0); 

document.unGroup() 

Availability 

Flash MX 2004. 

Usage 

document . unGroup( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; ungroups the current selection. See document . group( ). 
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Example 

The following example ungroups the elements in the current selection: 

fl . getDocumentDOM( ) .unGroup( ) ; 

document.unlockAIIEIements() 

Availability 

Flash MX 2004. 
Usage 

document . unl ockAl 1 El ements ( ) 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; unlocks all locked elements on the currently selected frame. See el ement . 1 ocked. 
Example 

The following example unlocks all locked objects in the current frame: 

f 1 . ge t Document DOM ( ) . unl ockAl 1 El ements ( ) ; 

document.viewMatrix 

Availability 

Flash MX 2004. 

Usage 

document . vi ewMatri x 

Description 

Read-only property; a Matrix object. The vi ewMatri x is used to transform from object space to 
document space when the document is in edit mode. The mouse location, as a tool receives it, is 
relative to the object that is currently being edited. 

For example, if you create a symbol, double-click to edit it, and draw with the polyStar tool, the 
point (0,0) will be at the registration point of the symbol. However, the drawingLayer object 
expects values in document space, so if you draw a line from (0,0) using the drawingLayer, it will 
start at the upper left corner of the Stage. The vi ewMatri x provides a way to transform from the 
space of the object being edited to document space. 

Example 

The following example gets the value of the vi ewMatri x property: 
var mat = fl . getDocumentD0M( ). vi ewMatri x ; 
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document.width 

Availability 

Flash MX 2004. 

Usage 

document.width 

Description 

Property; an integer that specifies the width of the document (Stage) in pixels. See 

document . he i ght. 

Example 

The following example sets the width of the Stage to 400 pixels. 

fl .getDocumentDOMt ) .width= 400; 

document.xmlPanelO 

Availability 

Flash MX 2004. 
Usage 

document . xml Panel ( fileURI ) 
Parameters 

fi leURI A string that specifies the path, expressed as a file://URL, to the XML file defining the 
controls in the panel. The full path is required. 

Returns 

An object that has properties defined for all controls defined in the XML file. All properties are 
returned as strings. The returned object will have one predefined property named "dismiss" that 
will have the string value "accept" or "cancel " . 

Description 

Method; posts a XMLUI dialog box. See f 1 . xml ui . 
Example 

The following example loads the Test.xml file and displays each property contained within it: 

var obj = fl .getDocumentDOMt ) .xml Panel (fl .configURI + "Commands/Test . xml ") ; 
for (var prop in obj) ( 

fl . tracet "property " + prop + " = " + obj[prop]); 

I 
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drawingLayer object 

Availability 

Flash MX 2004. 
Description 

The drawingLayer object is accessible from JavaScript as a child of the flash object. The 
drawingLayer object is used for extensible tools when the user wants to temporarily draw while 
dragging — for example, when creating a selection marquee. You should call 
drawingLayer. beg inFrame( ) before you call any other drawingLayer methods . 

Method summary for the drawingLayer object 



The following 


methods are av 


ailable for the drawingLayer object: 


Methods 




Description 


drawingLayer 


. begi nDraw( ) 


Method; puts Flash in drawing mode. 


drawi ngLayer 


. begi nFrame( ) 


Method; erases what was previously drawn using the drawingLayer 
and prepares for more drawing commands. 


drawingLayer 


cubi cCurveTo( ) 


Method; draws a cubic curve from the current pen location using the 
parameters as the coordinates of the cubic segment. 


drawingLayer 


curveTo( ) 


Method; draws a quadratic curve segment starting at the current 
drawing position and ending at a specified point. 


drawingLayer 


drawPath( ) 


Method; draws the specified path. 


drawingLayer 


. endDraw( ) 


Method; exits drawing mode. 


drawingLayer 


,endFrame( ) 


Method; signals the end of a group of drawing commands. 


drawingLayer 


1 i neTo( ) 


Method; draws a line from the current drawing position to the point 
(x,y). 


drawingLayer 


moveTo( ) 


Method; sets the current drawing position. 


drawingLayer 


. newPath ( ) 


Method; returns a new Path object. 


drawingLayer 


.setCol or( ) 


Method; sets the color of subsequently drawn data. 



drawingl_ayer.beginDraw() 

Availability 

Flash MX 2004. 
Usage 

drawi ngLayer . begi nDraw ( [pers i stentDrawl ) 
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Parameters 

pers i stentDrau A Boolean value (optional). If set to true, it indicates that the drawing in the 
last frame remains on the Stage until a new begi nDraw( ) or begi nFrame( ) call is made. (In this 
context, frame refers to where you start and end drawing; it does not refer to Timeline frames.) 
For example, when users draw a rectangle, they can preview the outline of the shape while 
dragging the mouse. If you want that preview shape to remain after the user releases the mouse 
button, set persi stentDraw to true. 

Returns 

Nothing. 
Description 

Method; puts Flash in drawing mode. Drawing mode is used for temporary drawing while the 
mouse button is pressed. You typically use this method only when creating extensible tools. 

Example 

The following example puts Flash in drawing mode: 

fl .drawingLayer.beginDrawt ) ; 

drawingl_ayer.beginFrame() 

Availability 

Flash MX 2004. 
Usage 

drawingLayer.beginFramet ) 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; erases what was previously drawn using the drawingLayer and prepares for more drawing 
commands. Should be called after drawing Layer, begi nDraw( ). Everything drawn between 
drawi ng Layer . begi n Frame ( ) and an drawing Lay er.endFra me ( ) remains on the Stage until 
you call the next beginFramet ) and endFramet ). (In this context, frame refers to where you start 
and end drawing; it does not refer to Timeline frames.) You typically use this method only when 
creating extensible tools. 
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drawingl_ayer.cubicCurveTo() 

Availability 

Flash MX 2004. 
Usage 

drawi ngLayer . cubi cCurveTo {xlCtr 1 , ylCtrl , x2Ctl , y2Ctl , xEnd, yEnd) 
Parameters 

xlCtl A floating-point value that is the x location of the first control point. 

ylCtl A floating-point value that is the y location of the first control point. 

xZCt 1 A floating-point value that is the x position of the middle control point. 

yZCt 1 A floating-point value that is the y position of the middle control point. 

xEnd A floating-point value that is the x position of the end control point. 

yEnd A floating-point value that is the y position of the end control point. 
Returns 

Nothing. 
Description 

Method; draws a cubic curve from the current pen location using the parameters as the 
coordinates of the cubic segment. You typically use this method only when creating extensible 
tools. 

Example 

The following example draws a cubic curve using the specified control points: 

fl .drawingLayer.cubicCurveTo(0, 0, 1, 1, 2, 0); 

drawingl_ayer.curveTo() 

Availability 

Flash MX 2004. 
Usage 

drawingLayer.curveToCxCt 7, yCtl, xEnd, yEnd) 
Parameters 

xCtl A floating-point value that is the x position of the control point. 
yCt 1 A floating-point value that is the y position of the control point. 
xEnd A floating-point value that is the x position of the end control point. 
yEnd A floating-point value that is the y position of the end control point. 
Returns 
Nothing. 
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Description 

Method; draws a quadratic curve segment starting at the current drawing position and ending at a 
specified point. You typically use this method only when creating extensible tools. 

Example 

The following example draws a quadratic curve using the specified control points: 

f 1 . drawi ngLayer . curveTot 0 , 0, 2, 0); 

drawingLayer.drawPath() 

Availability 

Flash MX 2004. 
Usage 

drawing Layer. drawPatht path) 
Parameters 

path A Path object to draw. 
Returns 

Nothing. 
Description 

Method; draws the path specified by the path parameter. You typically use this method only 
when creating extensible tools. 

Example 

The following example draws a path specified by the Path object named gamePath: 
fl . drawi ngLayer. drawPath( game Path) ; 

drawingl_ayer.endDraw() 

Availability 

Flash MX 2004. 
Usage 

drawi ngLayer . endDraw( ) 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; exits drawing mode. Drawing mode is used when you want to temporarily draw while 
the mouse button is pressed. You typically use this method only when creating extensible tools. 
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Example 

The following example exits drawing mode: 

fl .drawingLayer.endDraw( ) ; 

drawingLayer.endFrame() 

Availability 

Flash MX 2004. 
Usage 

draw ing Layer. endFrameO 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; signals the end of a group of drawing commands. A group of drawing commands refers 
to everything drawn between drawingLayer.begirFrame( ) and drawing Lay er.endFrame( ). 
The next call to drawingLayer.beginFrame( ) will erase whatever was drawn in this group of 
drawing commands. You typically use this method only when creating extensible tools. 

drawingl_ayer.lineTo() 

Availability 

Flash MX 2004. 
Usage 

drawi ngLayer . 1 i neTo ( x, y) 
Parameters 

x A floating-point value that is the x coordinate of the end point of the line to draw. 

y A floating-point value that is the y coordinate of the end point of the line to draw. 
Returns 

Nothing. 
Description 

Method; draws a line from the current drawing position to the point (x,y). You typically use this 
method only when creating extensible tools. 

Example 

The following example draws a line from the current drawing position to the point (20,30): 
fl . drawing Lay er.l i neTo ( 20, 30 ) ; 
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drawingl_ayer.moveTo() 

Availability 

Flash MX 2004. 
Usage 

drawingLayer.moveTo(x, y) 
Parameters 

x A floating-point value that specifies the x coordinate of the position at which to start 
drawing. 

y A floating-point value that specifies the y coordinate of the position at which to start 
drawing. 

Returns 

Nothing. 
Description 

Method; sets the current drawing position. You typically use this method only when creating 
extensible tools. 

Example 

The following example sets the current drawing position at the point (10,15): 

f 1 . drawi ngLayer .moveTo ( 10 , 15); 

drawingl_ayer.newPath() 

Availability 

Flash MX 2004. 
Usage 

drawingLayer.newPath( ) 
Parameters 

None. 
Returns 

A Path object. 
Description 

Method; returns a new Path object. You typically use this method only when creating extensible 
tools. 

Example 

The following example returns a new Path object: 

fl . drawi ngLayer. newPatht ) ; 
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drawingLayer.setColorQ 



Availability 

Flash MX 2004. 
Usage 

drawing Layer. setColor( co lor) 
Parameters 

col or A color that is specified by a string, integer, or hexadecimal value. 
Returns 

Nothing. 
Description 

Method; sets the color of subsequently drawn data. Applies only to persistent data. To use this 
method, the parameter passed todrawingLayer.beginDrawO must be set to true. You typically 
use this method only when creating extensible tools. 

Example 

The following example draws a red line on the Stage: 



drawi ngLayer . begi nDraw( true ); 
drawingLayer.beginFramet ) ; 
drawing Lay er.setCol or ( "#ff 0000" 
drawi ngLayer. mo veTo(0,0) ; 
drawi ngLayer. lineTodOO, 100); 
drawingLayer.endFrameO; 
drawingLayer.endDraw( ) ; 
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Edge object 

Availability 

Flash MX 2004. 
Description 

The Edge object represents an edge of a shape on the Stage. 

Method summary for the Edge object 

The following methods are available for the Edge object: 



Method Description 



edge 


. getControl ( ) 


Method; gets a point object set to the location of the specified control point of 






the edge. 


edge 


.getHal f Edge( ) 


Method; returns a HalfEdge object. 


edge 


. setControl ( ) 


Method; sets the position of the control point of the edge. 


edge 


. spl i tEdge( ) 


Method; splits the edge into two pieces. 



Property summary for the Edge object 

The following properties are available for the Edge object: 
Property Description 

edge . id Read-only; an integer that represents a unique identifier for the edge, 

edge .isLi ne Read-only; an integer with a value of 0 or1. 

edge.getControl() 

Availability 

Flash MX 2004. 

Usage 

edge . getControl ( 7 ) 

Parameters 

7 An integer that specifies which control point of the edge to return. Specify 0 for the first 
control point, 1 for the middle control point, or 2 for the end control point. If the edge . i s Li ne 
property is true, the middle control point is set to the midpoint of the segment joining the 
beginning and ending control points. 

Returns 

The specified control point. 
Description 

Method; gets a point object set to the location of the specified control point of the edge. 
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Example 

The following example stores the first control point of the specified shape in the pt variable: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
var pt = shape. edges[0] .getControl (0) ; 

edge.getHalfEdge() 

Availability 

Flash MX 2004. 
Usage 

edge.getHalfEdget index) 
Parameters 

index An integer that specifies which half edge to return. The value of index must be either 0 
for the first half edge or 1 for the second half edge. 

Returns 

A HalfEdge object. 
Description 

Method; returns a HalfEdge object. 
Example 

The following example stores the half edges of the specified edge in the hEdgeO and hEdgeO 
variables: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 

var edge = shape. edges[0] ; 

var hEdgeO = edge . getHal f Edge ( 0 ) ; 

var hEdgel = edge . getHal f Edge ( 1 ) ; 

edge.id 
Availability 

Flash MX 2004. 

Usage 

edge . i d 

Description 

Read-only property; an integer that represents a unique identifier for the edge. 
Example 

The following example stores a unique identifier for the specified edge in the my_shape_i d 
variable: 

var shape = f 1 . getDocumentDOMt ) . sel ecti on [0] ; 
var my_shape_id = shape . edges [0] . i d ; 
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edge.isLine 

Availability 

Flash MX 2004. 

Usage 

edge . i s Li ne 

Description 

Read-only property; an integer with a value of 0 or 1 . A value of 1 indicates that the edge is a 
straight line. In that case, the middle control point bisects the line joining the two end points. 

Example 

The following example determines whether the specified edge is a straight line, and shows a value 
of 1 (it is a straight line) or 0 (it isn't a straight line) in the Output panel: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
f 1 . trace ( shape. edges [0] . i sLi ne) ; 

edge.setControl() 

Availability 

Flash MX 2004. 
Usage 

edge . setControl ( index, x, y ) 
Parameters 

index specifies which control point to set. Use values 0, 1, or 2 to specify the beginning, 
middle, and end control points, respectively. 

x A floating point value that specifies the horizontal location of the control point. If the Stage is 
in Edit or Edit-in-place mode, the point coordinate is relative to the edited object. Otherwise, the 
point coordinate is relative to the Stage. 

y A floating point value that specifies the vertical location of the control point. If the Stage is in 
Edit or Edit-in-place mode, the point coordinate is relative to the edited object. Otherwise, the 
point coordinate is relative to the Stage. 

Returns 

Nothing. 
Description 

Method; sets the position of the control point of the edge. You must call shape. beg in Ed it() 
before using this method. 
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Example 

The following example sets the beginning control point of the specified edge to the (0, 1) 
coordinates: 

x = 0; y = 1; 

var shape = f 1 . getDocumentDOMt ) . sel ecti on [0] ; 

shape . begi nEdi t ( ) ; 

shape . edges [0] . setControl ( 0 , x, y); 

shape. endEdit( ) ; 



edge.splitEdge() 

Availability 

Flash MX 2004. 

Usage 

edge . spl i tEdge ( t ) 

Parameters 

t A floating point value between 0 and 1 that specifies where to split the edge. A value of 0 
represents one end point, and 1 the other. For example, passing a value of 0.5 splits the edge in 
the middle, which, for a line is exactly in the center. If the edge represents a curve, 0.5 represents 
the parametric middle of the curve. 

Returns 

Nothing. 
Description 

Method; splits the edge into two pieces. You must call shape. beg inEditt ) before using this 
method. 

Example 

The following example splits the specified edge in half: 

var shape = fl . getDocumentDOMt ). sel ecti on [0] ; 

shape. beginEdit( ) 

shape. edges[0] .spl itEdge( 0.5 ); 

shape. endEditt ) 
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Effect object 

Availability 

Flash MX 2004. 
Description 

This is a single effect descriptor object. The f 1 . acti veEf f ect and the f 1 . effects properties 
contain this type of object. The Effect object represents an instance of a Timeline effect. 

Property summary for the Effect object 

In addition to the properties listed in the following table, Effect objects can also have user-defined 
parameters, which must be specified in the same XML file that specifies the effect. effectName 
and effect . sourceFi 1 e properties. These parameters specify which UI elements should be 



created (such as edit fields, check boxes, and list boxes), which is controlled by the type of effect 
you are creating. You can specify labels that will appear with the control in addition to default 
values. 


Property 


Description 


effect . effectName 


Read-only; a string that appears in the Context menu for effects. 


ef f ect . groupName 


Read-only; a string that represents the name of the effect group used for 
the hierarchical Context menu for effects. 


ef feet . sourceFi 1 e 


Read-only; a string that specifies the name of JSFL source file for the 
specified effect. 


effect . symbol Type 


Read-only; a string that specifies the type of symbol to create during the 
initial application of the effect. 


effect. useXMtToUI 


Property; a Boolean value that lets you override the default behavior of 
using XMLUI to construct a dialog box that consists of one or more controls. 



effect.effectName 

Availability 

Flash MX 2004. 

Usage 

effect . effectName 

Description 

Read-only property; a string that appears in the Context menu for effects. Each effect must be 
uniquely named. 

Example 

The following example stores the name of the current effect in the ef Name variable: 
var efName = f 1 . acti veEf feet . effectName ; 
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effect.groupName 

Availability 

Flash MX 2004. 

Usage 

effect . groupName 

Description 

Read-only property; a string that represents the name of the effect group used for the hierarchical 
Context menu for effects. If this value is an empty string, the effect appears ungrouped at the top 
level of the Context menu. The group name and effect name are specified in the XML file for the 
effect. 

Example 

The following example stores the group name of the current effect in the ef GroupName variable: 
var efGroupName = f 1 . acti veEf feet . groupName ; 

effect.sourceFile 

Availability 

Flash MX 2004. 

Usage 

effect . sourceFi 1 e 

Description 

Read-only property; a string that specifies the name of JSFL source file for the specified effect. 
This string is used to bind an XML parameter file to its JSFL effect implementation. You must 
include this XML parameter in the XML file for the effect. 

Example 

The following example stores the name of the JSFL effect source file in the ef SourceFi 1 e 
variable: 

var efSourceFile = f 1 . acti veEf feet . sourceFi 1 e; 

effect .symbolType 

Availability 

Flash MX 2004. 

Usage 

effect . symbol Type 
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Description 

Read-only property; a string that specifies the type of symbol to create during the initial 
application of the effect. The supported types are: "graphic", "movie cl i p", and "button". If 
a symbol type was not specified when the effect was created, the default value is "graphic". 

Example 

The following example stores the symbol type for the current effect in the ef Type variable: 
var efType = f 1 . acti veEf feet . symbol Type ; 

effect.useXMLToUl 

Availability 

Flash MX 2004. 

Usage 

effect.useXMLToUl 

Description 

Property; a Boolean value that lets you override the default behavior of using XMLUI to construct 
a dialog box that consists of one or more controls. The default value is true. If set to f al se, the 
standard XMLUI dialog box will not be posted and you are responsible for posting a UI. 

Example 

The following example specifies that the effect does its own UI: 

function conf i gureEf f ect ( ) j 

fl . acti veEf feet . useXMLToUI = false; 

} 
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Element object 

Availability 

Flash MX 2004. 
Description 

Everything that appears on the Stage is of the type Element. The following code example lets you 
select an element: 

f 1 . get Document DOM ( ) .getTimel ine( ) . frame s [0] .1 ayers[0] .el ements [0] ; 

Method summary for the Element object 

The following methods are available for the Element object: 
Method Description 

el ement .getPersistentData() Retrieves the value of the data specified by the name parameter. 

el ement . has Persi stentData ( ) Determines whether the specified data has been attached to the 

specified element. 

el ement . removePersi stentData ( ) Removes any persistent data with the specified name that has 

been attached to the object. 

el ement . set Per si stentData ( ) Stores data with an element. 



Property summary for the Element object 

The following properties are available for the Element object: 



Property Description 



el ement 


.depth 


Read-only; an integer that has a value greater than 0 for the 
depth of the object in the view. 


el ement 


, el ementType 


Read-only; a string that represents the type of the specified 
element. 


el ement 


.height 


A float value that specifies the height of the element in pixels. 


el ement 


.left 


Read-only; a float value that represents the left side of the 
element. 


el ement 


. 1 ocked 


A Boolean value: true if the element is locked; fal se otherwise. 


el ement 


.matrix 


A Matrix object. The matrix has properties a , b, c, d, tx, and 
ty. a, b, c, d are floating point values; tx and ty are 
coordinates. 


el ement 


, name 


A string that specifies the name of the element, normally referred 
to as the Instance name. 


el ement 


.top 


Read-only; top side of the element. 


el ement 


.width 


A float value that specifies the width of the element in pixels. 
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element.depth 

Availability 

Flash MX 2004. 

Usage 

el ement . depth 

Description 

Read-only property; an integer that has a value greater than 0 for the depth of the object in the 
view. The drawing order of objects on the Stage specifies which one is on top of the others. Object 
order can also be managed with the Modify > Arrange menu item. 

Example 

The following example displays the depth of the specified element in the Output panel: 

// select an object then run this script 
fl . tracet " Depth of selected object: " + 
f 1 . ge t Document DOM ( ). select i on [0] . depth); 

See the example for el ement . el ementType. 

element.elementType 

Availability 

Flash MX 2004. 

Usage 

el ement . el ementType 

Description 

Read-only property; a string that represents the type of the specified element. The value is one of 
the following: "shape", "text", "instance", or "shapeObj". A "shapeObj" is created with an 
extensible tool. 

Example 

The following example stores the type of the first element in the eType variable: 

// In a new file, place a movie clip on first frame top layer, 
// then run this line of script 
var eType = 

f 1 . ge t Document DOM ( ) . getTimel i ne ( ) . 1 ayers [0] . frames [0] .el ement s [0] . el ementTy 
pe; //eType = instance 

The following example displays several properties for all the elements in the current layer or 
frame: 

var tl = f 1 . getDocumentDOMt ) . getTi mel i ne( ) 

var elts = tl . 1 ayers [tl . current Layer] . frames [tl . currentFrame] . el ements ; 
for (var x = 0; x < elts. length; x++) { 
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va r el t = el ts [x] ; 

f 1 . tracet " El ement "+ x +" Name = " + elt.name + " Type = " + el t . el ementType 
+ " location = " + el t . 1 eft + "," + elt.top + " Depth = " + elt. depth); 

} 

element.getPersistentData() 

Availability 

Flash MX 2004. 
Usage 

el ement . getPersi stentData ( name ) 
Parameters 

name A string that identifies the data to be returned. 
Returns 

The data specified by the name parameter, or 0 if the data doesn't exist. 
Description 

Method; retrieves the value of the data specified by the name parameter. The type of data depends 
on the type of the data that was stored (see el ement . set Persi stentData ( )). Only symbols and 
bitmaps support persistent data. 

Example 

The following example sets and gets data for the specified element, shows its value in the Output 
panel, and then removes the data: 

// at least one symbol or bitmap is selected in the first layer, first frame 
var elt = fl . getDocumentDOMt ). getTi mel i ne( ). 1 ayers [0] . frames [0] . el ements [0] ; 
elt. setPersistentData(" my Data "."integer", 12); 
if (elt.hasPersistentData("myData")){ 

fl . tracet "myData = "+ el t . getPersi stentData ( "myData ")) ; 

el t . removePersi stentData ( "myData" ); 

fl . tracet "myData = "+ el t . getPersi stentData ( "myData ")) ; 

) 

element.hasPersistentData() 

Availability 

Flash MX 2004. 
Usage 

el ement . hasPersi stentData ( name ) 
Parameters 

name A string that specifies the name of the data item to test. 
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Returns 

A Boolean value: true if the specified data is attached to the object; false otherwise. 
Description 

Method; determines whether the specified data has been attached to the specified element. Only 
symbols and bitmaps support persistent data. 

Example 

See el ement .getPersistentData( ). 

element.height 

Availability 

Flash MX 2004. 

Usage 

el ement . hei ght 

Description 

Property; a float value that specifies the height of the element in pixels. 

Note: Do not use this property to resize a text field. Instead, select the text field and use 
document . setTextRectangl e( ). Using this property with a text field scales the text. 

Example 

The following example sets the height of the specified element to 100: 

f 1 . get Document DOM ( ) .getTimel ine( ) . 1 ayers [0] . frame s [0] .el ement s [0] .height = 
100; 

element.left 

Availability 

Flash MX 2004. 

Usage 

el ement . 1 eft 

Description 

Read-only property; a float value that represents the left side of the element. The value of 
el ement . 1 eft is relative to the upper left of the Stage for elements that are in a scene, and is 
relative to the symbol's registration point if the element is stored within a symbol. Use 

document .setSelectionBoundsU or document . moveSel ect i on By ( ) to set this property. 

Example 

The following example illustrates how the value of this property changes when an element is 
moved: 

//Select an element on the stage and then run this script 
var sel = f 1 . getDocumentD0M( ) . sel ecti on [0] ; 
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fl .trace( "Left (before) = " + sel.left); 

f 1 . get Document DOM ( ).moveSelectionBy({x:100, y : 0 ) ) ; 

fl .tracet "Left (after) = " + sel.left); 

See the el ement . el ementfype example. 

element.locked 

Availability 

Flash MX 2004. 

Usage 

el ement . 1 ocked 

Description 

Property; a Boolean value: true if the element is locked; fal se otherwise. If the value of 
el ement . el ementfype is "shape", this property is ignored. 

Example 

The following example locks the first element in the first frame, top layer: 

// similar to Modify > Arrange > Lock: 

f 1 . get Document DOM ( ) .getfimel ine( ) .1 ayers[0] . frame s [0] .el ement s [0] .locked = 
true ; 

element.matrix 

Availability 

Flash MX 2004. 

Usage 

el ement . matri x 

Description 

Property; a Matrix object. A matrix has properties a, b, c, d, tx, and ty. The a, b, c, and d 
properties are floating point values; the tx and ty properties are coordinates. 

Example 

The following example moves the specified element by 10 pixels in x and 20 pixels in y: 

var mat = 

f 1 . ge t Document DOM ( ) .getfimel i ne ( ) . 1 ayers [0] . frames [0] .el ement s [0] .matrix; 
mat.tx += 10; 
mat.ty += 20; 

fl . get Document DOM ( ) .getfimel ine( ) .1 ayers[0] . frame s[0] .elements[0] .matrix = 
mat ; 
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element.name 

Availability 

Flash MX 2004. 

Usage 

el ement . name 

Description 

Property; a string that specifies the name of the element, normally referred to as the Instance 
name. If the value of el ement . el ementType is "shape", this property is ignored. 

Example 

The following example sets the Instance name of the first element in Frame 1, top layer to 
"cl i p_mc" : 

fl . get Document DOM ( ) .getTimel ineU.l ay ers[0] . frame s[0] .elements[0] .name = 
"cl i p_mc" ; 

See the el ement . el ementType example. 

element.removePersistentData() 

Availability 

Flash MX 2004. 
Usage 

el ement . removePersi stentData ( name ) 
Parameters 

name A string that specifies the name of the data to remove. 
Returns 

Nothing. 
Description 

Method; removes any persistent data with the specified name that has been attached to the object. 
Only symbols and bitmaps support persistent data. 

Example 

See el ement .getPersi stentData ( ). 

element.setPersistentData() 

Availability 

Flash MX 2004. 
Usage 

el ement . setPersi stentData ( name, type, value ) 
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Parameters 

name A string that specifies the name to associate with the data. This name is used to retrieve 
the data. 

type A string that defines the type of the data. The allowable values are "integer", 
" i nteger Array ", "double", "doubl eArray ", "string", and "byteArray ". 

va 1 ue Specifies the value to associate with the object. The data type of va 1 ue depends on the 
value of the type parameter. The specified value should be appropriate to the data type specified 
by the type parameter. 

Returns 

Nothing. 
Description 

Method; stores data with an element. The data is available when the FLA file containing the 
element is reopened. Only symbols and bitmaps support persistent data. 

Example 

See el ement .getPersistentData( ). 

element.top 

Availability 

Flash MX 2004. 

Usage 

el ement . top 

Description 

Read-only property; top side of the element. The value of el ement . top is relative to the upper 
left of the Stage for elements that are in a scene, and is relative to the symbol's registration point if 
the element is stored within a symbol. Use document . setSel ecti onBounds ( ) or 
document .moveS el ecti on By ( ) to set this property. 

Example 

The following example shows how the value of this property changes when an element is moved: 

//Select an element on the stage and then run this script 

var sel = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 

f 1 . tracet "Top (before) = " + sel. top); 

f 1 . get Document DOM ( ).moveSelectionBy({x:0, y:100}); 

f 1 . trace( "Top (after) = " + sel. top); 

See the el ement . el ementType example. 
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element.width 

Availability 

Flash MX 2004. 

Usage 

el ement. width 

Description 

Property; a float value that specifies the width of the element in pixels. 

Note: Do not use this property to resize a text field. Instead, select the text field and use 
document . setTextRectangl e( ). Using this property with a text field scales the text. 

Example 

The following example sets the width of the specified element to 100: 

f 1 . getDocumentDOM( ) .getTimel ine( ) . 1 ayers [0] . frame s [0] .el ement s [0] . wi dth= 100 ; 
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EmbeddedVideolnstance object 

Inheritance Element object > Instance object > EmbeddedVideolnstance object 
Availability 

Flash MX 2004. 
Description 

The EmbeddedVideolnstance object is a subclass of Instance object. There are no unique 
methods or properties of EmbeddedVideolnstance. 
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Fill object 



Availability 

Flash MX 2004. 
Description 

This object contains all the properties of the Fill color setting of the toolbar or of a selected shape. 
To retrieve a Fill object, use document . getCustomFi 1 1 ( ). 

Property summary for the Fill object 

The following properties are available for the Fill object: 



Property Description 



fill 


. col or 


A color string in hexadecimal format, such as #rrggbb, or an integer containing the 
color value. 


fill 


. col orArray 


An array of colors in gradient. 


fill 


.matrix 


A Matrix object that defines the placement, orientation, and scales for gradient 
fills. 


fill 


. posArray 


An array of integers, each in the range 0 ... 255, indicating the position of the 
corresponding color. 


fill 


. styl e 


A string that specifies the fill style. 



fill. color 

Availability 

Flash MX 2004. 

Usage 

fill .color 

Description 

Property; a color string in hexadecimal format, such as #rrggbb, or an integer containing the color 
value. 

Example 

The following example sets the fill color of the current selection: 

var fill = fl . getDocumentDOM( ). getCustomFi 1 1 () ; 
fill .color = 1 #FFFFFF 1 ; 

fl .getDocumentDOM( ) . setCustomFi 1 1 ( fill ); 
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fill.colorArray 

Availability 

Flash MX 2004. 

Usage 

fill, col orArray 

Description 

Property; an array of colors in gradient. This property is available only if the value of the 
fill . styl e property is either " radi al Gradi ent " or " 1 i nearGradi ent ". 

Example 

The following example displays the color array of the current selection, if appropriate, in the 
Output panel. 

var fill = f 1 . getDocumentDOM( ) . getCustomFi 1 1 ( ) ; 

if(fill. style == "1 i nearGradi ent" || fill. style == " radi al Gradi ent " ) 
alerttfill .colorArray) ; 

fill, matrix 
Availability 

Flash MX 2004. 

Usage 

f i 1 1 .matrix 

Description 

Property; a Matrix object that defines the placement, orientation, and scales for gradient fills. 

fill.posArray 

Availability 

Flash MX 2004. 

Usage 

fill. posArray 

Description 

Property; an array of integers, each in the range 0 ... 255, indicating the position of the 
corresponding color. This property is available only if the value of the fill . styl e property is 
either " radi a 1 Gradi ent " or " 1 i nearGradi ent ". 

Example 

The following example specifies the colors to use in a linear gradient for the current selection: 

var fill = fl . getDocumentD0M( ). getCustomFi 1 1 () ; 
fill. style = "1 inearGradient" ; 

fill.colorArray = [ OxOOffOO, OxffOOOO, OxOOOOff ]; 
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fill .posArray = [0, 100, 200]; 

fl .getDocumentDOM( ) . setCustomFi 1 1 ( fill ); 

fill.style 

Availability 

Flash MX 2004. 

Usage 

fill .style 

Description 

Property; a string that specifies the fill style. Valid values are: "solid", " 1 i n e a r G r a d i e n t " , 

" radi al Gradi ent ", and "noFi 1 1 ". If an object has no fill, this property has a value of "noFi 1 1 ". 

If this value is "1 i nearGradi ent " or " radi a 1 Gradi ent ", the properties f i 1 1 . col or Array and 
fill. posArray are also available. 

Example 

The following example specifies the colors to use in a linear gradient for the current selection: 

var fill = f 1 . getDocumentD0M( ) . getCustomFi 1 1 ( ) ; 
fill . styl e= " 1 i nea rGradi ent " ; 

fill .colorArray = [ OxOOffOO, OxffOOOO, OxOOOOff ]; 

fill .posArray = [0, 100, 200]; 

fl .getDocumentD0M( ) .setCustomFi 1 1 ( fill ); 



160 Chapter 3: Objects 



flash object 

Availability 

Flash MX 2004. 
Description 

The flash object represents the Flash application. 

Method summary for the flash object 

The following methods can be used with the flash object. 



Method Description 



f 1 .browseForFi 1 eURL( ) Opens a File Open or File Save system dialog box and lets the user 

specify a file to be opened or saved. 

f 1 . cl oseAl 1 ( ) Closes all open documents, displaying the Save As dialog box for 

any documents that were not previously saved. 

fl . closeDocument( ) Closes the specified document. 

f 1 . createDocument( ) Opens a new document and selects it. 

f 1 . enabl elmmedi ateUpdates( ) Lets the script developer enable immediate visual updates of the 

Timeline when executing effects. 

fl . fileExistst ) Checks whether a file already exists on disk. 

f 1 . f ind Document Index ( ) Finds the index of an open document with the specified name. 

f 1 . getDocumentDOM( ) Retrieves the DOM (Document object) of the currently active 

document. 

fl .mapPl ayerURK ) Maps an escaped Unicode URL to a UTF-8 or MBCS URL. 

f 1 .open Documents ) Opens a Flash (FLA) document for editing in a new Flash Document 

window and gives it the focus. 

f 1 . open Project ( ) Opens a Flash Project (FLP) file in the authoring tool for editing. 

f 1 . openScr i pt ( ) Opens a script (JSFL, AS, ASC) or other file (XML, TXT) in the 

Flash text editor. 

f 1 .qui t ( ) Quits Flash, prompting the user to save any changed documents. 

f 1 . rel oadEffects( ) Reloads all effects descriptors defined in the user's Configuration 

Effects folder. 

f 1 .rel oadfool s( ) Rebuilds the toolbar from the toolconfig.xml file. Used only when 

creating extensible tools. 

f 1 . revertDocument( ) Reverts the specified FLA document to its last saved version. 

f 1 . runScri pt( ) Executes a JavaScript file. 

f 1 . saveAl 1 ( ) Saves all open documents, displaying the Save As dialog box for 

any documents that were not previously saved. 

f 1 . saveDocument( ) Saves the specified document as a FLA document. 
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Method 



Description 



fl 


. sa veDocumentAs ( ) 


Displays the Save As dialog box for the specified document. 


fl 


. setActi veWi ndow( ) 


Sets the active window to be the specified document. 


fl 


.tracet ) 


Sends a text string to the Output panel. 



Property summary for the flash object 

The following properties can be used with the flash object. 



Properties Description 



■Fl 
T 1 


. acti v e E f f ec t 


r\odU UMly, IMtJQMoClUUJoCllUI LMtrCUIIoMloMoClUfcMNyappilfcJU. 


fi 


.componentsPanel 


Read-only; a componentsPanel object, which represents the 
Components panel. 


fl 


. conf i g □ i rectory 


Read-only; a string that specifies the full path for the local user's 
Configuration folder as a platform-specific path. 


fl 


. conf i gURI 


Read-only; a string that specifies the full path for the local user's 
Configuration directory in a URI format (file:///). 


fl 


. createNewDocLi st 


Read-only; an array of strings that represent the various types of 
documents that can be created. 


fi 


.createNewDocListType 


Read-only; an array of strings that represent the file extensions of 
the types of documents that can be created. 


fi 


. createNewTempl ateLi st 


Read-only; an array of strings that represent the various types of 
templates that can be created. 


fi 


.documents 


Read-only; an array of Document objects (see Document object) 
that represent the documents (FLA files) that are currently open for 
editing. 


fi 


. drawi ngLayer 


Read-only; the drawingLayer object that an extensible tool should 
use when the user wants to temporarily draw while dragging. 


fl 


.effects 


Read-only; an array of Effect objects (see Effect object), based on 
XML parameter file. 


fl 


.Math 


Read-only; the Math object >provides methods for matrix and point 
operations. 


fl 


.mruRecentFi 1 eLi st 


Read-only; an array of the complete filenames in the Most Recently 
Used (MRU) list that the authoring tool manages. 


fi 


.mruRecentFileListType 


Read-only; an array of the file types in the MRU list that the 
authoring tool manages. 


fi 


. outputPanel 


Read-only; reference to the outputPanel object. 


fl 


.tool s 


Read-only; an array of Tools objects. 


fl 


.version 


Read-only; returns the long string version of the Flash authoring 
tool, including platform. 


fi 


. xml ui 


Read-only; an XMLUI object. 
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fl.activeEffect 

Availability 

Flash MX 2004. 

Usage 

f 1 . acti veEf f ect 

Description 

Read-only property; the Effect object for the current effect being applied. For a list of properties 
available to f 1 . acti veEf f ect, see "Property summary for the Effect object" on page 146. 

Example 

The following example stores an object that represents the current effect in the ef variable. 

var ef = fl.activeEffect; 

fl.browseForFileURL() 

Availability 

Flash MX 2004. 
Usage 

f 1 . browseForFi 1 eURL( browseType [, title [, previewArea ] ]) 
Parameters 

browseType A string that specifies the type of file browse operation. Valid values are " open ", 
"select" or "save". The values "open" and "select" open the system File Open dialog box. 
Each value is provided for compatibility with Dreamweaver. The value "save" opens a system 
File Save dialog box. 

title A string that specifies the title for the File Open or File Save dialog box. If this parameter 
is omitted, a default value is used. This parameter is optional. 

previ ewArea An optional parameter that is ignored by Flash and Fireworks and is present only 
for compatibility with Dreamweaver. 

Returns 

A string containing the URL of the file. 
Description 

Method; opens a File Open or File Save system dialog box and lets the user specify a file to be 
opened or saved. 

Example 

The following example lets the user choose a FLA file to open and then opens the file. (The 

f 1 . browser For Fi 1 eURL( ) method can browse for any type of file, but f 1 . open Document ( ) can 

open only FLA files.) 
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var fileURL = f 1 . browseFor Fi 1 eURL( "open " , "Select file"); 
var doc = f 1 . openDocument ( f i 1 eURL) ; 

fl.closeAIIO 

Availability 

Flash MX 2004. 

Usage 

fl .closeAll ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; closes all open documents, displaying the Save As dialog box for any documents that 
were not previously saved. The method prompts the user, if necessary, but does not terminate the 
application. See also fl . cl oseDocument( ). 

Example 

The following code closes all open documents. 

fl .closeAllO; 

fl.closeDocument() 

Availability 

Flash MX 2004. 
Usage 

f 1 . cl oseDocument ( documentObject [, bPromptToSaveChanges] ) 
Parameters 

documentObject, [ bPromptToSaveChanges] 

documentObject A Document object. If documentObject refers to the active document, the 
Document window might not close until the script that calls this method finishes executing. 

bPromptToSa veChanges A Boolean value. If it is false, the user is not prompted if the 
document contains unsaved changes; that is, the file is closed and the changes are discarded. If the 
value is true, and if the document contains unsaved changes, the user is prompted with the 
standard yes-or-no dialog box. The default value is true. This parameter is optional. 

Returns 

A Boolean value: true if successful; false otherwise. 
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Description 

Method; closes the specified document. See also f 1 . cl oseAl 1 ( ). 
Example 

The following example illustrates two ways of closing a document. 

//closes the specified document and prompts to save changes 
f 1 . cl oseDocument ( f 1 . documents [0] ) ; 

fl . cl oseDocument ( fl . documents [0] , true); //use of true is optional 
//closes the specified document without prompting to save changes 
f 1 . cl oseDocument ( f 1 . documents [0] , false); 

fl.componentsPanel 

Availability 

Flash MX 2004. 

Usage 

f 1 . componentsPanel 

Description 

Read-only property; a componentsPanel object, which represents the Components panel. 
Example 

The following example stores a componentsPanel object in the comPanel variable, 
var comPanel = fl.componentsPanel; 

fl.configDirectory 

Availability 

Flash MX 2004. 

Usage 

f 1 . conf i gDi rectory 

Description 

Read-only property; a string that specifies the full path for the local user's Configuration directory 
in a platform-specific format. To specify this path in a URI format (file:///), use 
fl .configURI. 

Example 

The following example displays the Configuration directory in the Output panel. 

fl.tracet "My local configuration directory is " + fl.configDirectory ); 
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fl.configURI 

Availability 

Flash MX 2004. 

Usage 

fl .configURI 

Description 

Read-only property; a string that specifies the full path for the local user's Configuration directory 
in a URI format (f i 1 e : ///). See also f 1 . conf i gDi rectory. 

Example 

The following example runs a specified script. Using fl .configURI lets you specify the location 
of the script without knowing which platform the script is running on. 

// to run a command in your commands menu change "fest.Jsfl" 
// to the command you wish to run in the line below 
f 1 . runScri pt ( fl.configURI + "Commands/Test . j sfl " ); 

fl.createDocument() 

Availability 

Flash MX 2004. 
Usage 

f 1 . createDocument ( [docType] ) 
Parameters 

docType A string that specifies the type of document to create. Valid values are "ti mel i ne", 
"presentation", and "application". The default value is "ti mel i ne". This parameter is 
optional. 

Returns 

If successful, returns the Document object for the newly created document. If an error occurs, the 
value is undef i ned. 

Description 

Method; opens a new document and selects it. Values for size, resolution, and color are the same 
as the current defaults. 

Example 

The following example creates different types of documents. 

//create a fimel ine-based Flash Document 
fl .createDocument( ) ; 
fl .createDocumentt "timel ine" ) ; 
//create a Slide Presentation document 
f 1 . createDocument ( "presentati on" ) ; 
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//create a Form Application document 
fl .createDocument( "appl i cati on" ) ; 

fl.createNewDocList 

Availability 

Flash MX 2004. 

Usage 

fl . createNewDocLi st 

Description 

Read-only property; an array of strings that represent the various types of documents that can be 
created. 

Example 

The following example displays the types of documents that can be created in the Output panel. 

fl . tracet "Number of choices " + fl . createNewDocLi st . 1 ength ) ; 
for (i = 0; i < fl . createNewDocLi st . 1 ength ; i++) 
fl . tracet "choi ce : " + f 1 . createNewDocLi st[ i ]) ; 

fl.createNewDocListType 

Availability 

Flash MX 2004. 
Usage 

fl . createNewDocLi stType 
Description 

Read-only property; an array of strings that represent the file extensions of the types of documents 
that can be created. The entries in the array correspond directly (by index) to the entries in the 

f 1 . createNewDocLi st array. 

Example 

The following example displays the extensions of the types of documents that can be created in 
the Output panel. 

fl . trace( "Number of types " + fl . createNewDocLi stfype . 1 ength ) ; 
for (i = 0; i < fl . createNewDocLi stfype . 1 ength ; i++) fl .trace( "type: " + 
fl .createNewDocListfype[i]) ; 

fl.createNewTemplateList 

Availability 

Flash MX 2004. 
Usage 

fl . createNewTempl ateLi st 
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Description 

Read-only property; an array of strings that represent the various types of templates that can be 
created. 

Example 

The following example displays the types of templates that can be created in the Output panel. 

fl . trace( "Number of template types: " + f 1 . createNewTempl ateLi st . 1 ength ) ; for 
(i = 0; i < fl . createNewTempl ateLi st . 1 ength ; i++) fl .trace( "type: " + 
f 1 . createNewTempl ateLi st[i ] ) ; 

fl. documents 

Availability 

Flash MX 2004. 

Usage 

f 1 . documents 

Description 

Read-only property; an array of Document objects that represent the documents (FLA files) that 
are currently open for editing. 

Example 

The following example stores an array of open documents in the docs variable, 
var docs = fl . documents ; 

The following example displays the names of currendy open documents in the Output panel. 

for (doc in fl . documents ) { 

fl . tracetfl . documents [doc] .name) ; 

} 

fl.drawingLayer 

Availability 

Flash MX 2004. 

Usage 

f 1 . drawi ngLayer 

Description 

Read-only property; the drawingLayer object that an extensible tool should use when the user 
wants to temporarily draw while dragging (for example, when creating a selection marquee). 

Example 

See drawingLayer.setColor( ). 
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fl. effects 

Availability 

Flash MX 2004. 

Usage 

f 1 . effects 

Description 

Read-only property; an array of Effect objects, based on XML parameter file. These are not 
effects, but a description of effects. The array length corresponds to the number of effects (based 
on the XML parameter definition files, not the number of JSFL implementation files) registered 
when the program opens. 

Example 

To return the first registered effect, use the following: 

ef = fl .effects[0] 

fl.enablelmmediateUpdates() 

Availability 

Flash MX 2004. 
Usage 

f 1 . enabl elmmedi atellpdatest bEnabl eUpdates) 
Parameters 

bEnabl eUpdates A Boolean value that specifies whether to enable (true) or disable (f al se) 
immediate visual updates of the Timeline when executing effects. 

Returns 

Nothing. 
Description 

Method; lets the script developer enable immediate visual updates of the Timeline when 
executing effects. Immediate updates are normally suppressed so the user does not see 
intermediate steps that can be visually distracting and can make the effect appear to take longer 
than necessary. This method is purely for debugging purposes and should not be used in effects 
that are deployed in the field. After the effect completes, the internal state is reset to suppress 
immediate updates. 

Example 

The following example enables immediate updates. 

fl . enabl elmmedi ateUpdates ( true ) ; 

f 1 . trace( " Immedi ate updates are enabled"); 
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fl.fileExists() 

Availability 

Flash MX 2004. 
Usage 

fl . fil eExi sts ( fileURI ) 
Parameters 

f / 7 eURI A string that contains the path to the file. 
Returns 

A Boolean value: true if the file exists on disk; fal se otherwise. 
Description 

Method; checks whether a file already exists on disk. 
Example 

The following example outputs trueorfalseto the Output panel for each specified file, 
depending on whether the file exists. 

al ert( f 1 . f i 1 eExi sts ( "f i 1 e : ///C | /exampl e. f 1 a" ) ) ; 
al ert( f 1 . f i 1 eExi sts( "f i 1 e : ///C j /exampl e. jsf 1 " ) ) ; 
alerttfl . fi 1 eExi sts ("")) ; 

fl.findDocumentlndex() 

Availability 

Flash MX 2004. 
Usage 

f 1 . f i ndDocumentIndex( name ) 
Parameters 

name The document name for which you want to find the index. The document must be open. 
Returns 

An integer that is the index of the document. 
Description 

Method; finds the index of an open document with the specified name. 
Example 

The following example stores an indexed integer that represents the position of test.fla in the 
fl .documents array in the doclndex variable. For example, if fl . documents [3] is test.fla, then 
the value of doclndex is 3. 

var doclndex = f 1 . f i ndDocument Index( "test . f 1 a " ) ; 
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fl.getDocumentDOM() 

Availability 

Flash MX 2004. 

Usage 

fl .getDocumentDOM( ) 

Parameters 

None. 
Returns 

A Document object, or nul 1 if no documents are open. 
Description 

Method; retrieves the DOM (Document object) of the currently active document (FLA file). If 
one or more documents are open but a document is not currently focused (for example, a JSFL 
file is focused) , retrieves the DOM of the most recently active document. 

Example 

The following example displays the name of the current or most recently active document in the 
Output panel: 

var currentDoc = f 1 . getDocumentDOM( ) ; 
fl .trace(currentDoc.name); 

fl.mapPlayerURLO 

Availability 

Flash MX 2004. 
Usage 

fl .mapPl ayerURK URI [, returnMBCS^ ) 
Parameters 

URI A string that contains the escaped Unicode URL to map. 

returnMBCS A Boolean value that you must set to true if you want an escaped MBCS path 
returned. Otherwise, the method returns UTF-8. The default value is f al se. This parameter is 
optional. 

Returns 

A string that is the converted URL. 
Description 

Method; maps an escaped Unicode URL to a UTF-8 or MBCS URL. Use this method when the 
string will be used in ActionScript to access an external resource. You must use this method if you 
need to handle multibyte characters. 
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Example 

The following example converts a URL to UTF-8 so the player can load it. 

var url = MMExecute( "f 1 .mapPl ayerURLt " + myURL + ", false);" ); 
mc . 1 oadMovi e ( url ) ; 

fl.Math 

Availability 

Flash MX 2004. 

Usage 

fl .Math 

Description 

Read-only property; the Math object provides methods for matrix and point operations. 
Example 

The following shows the transformation matrix of the selected object, and its inverse. 

//Select an element on the stage, then run this script 
var mat =f 1 . getDocumentDOMt ) . sel ecti on[0] .matri x ; 
for(var prop in mat)( 

fl . tracet "mat . "+prop+" = " + mat[prop]); 

} 

var invMat = f 1 . Math . i nvertMatri x( mat ); 
for(var prop in invMat) { 

fl .tracet "invMat. "+prop+" = " + i nvMat[prop] ) ; 

} 

fl.mruRecentFileList 

Availability 

Flash MX 2004. 

Usage 

fl . mruRecent Fi 1 eLi st 

Description 

Read-only property; an array of the complete filenames in the Most Recently Used (MRU) list 
that the authoring tool manages. 

Example 

The following example displays the number of recently opened files, and the name of each file, in 
the Output panel. 

fl . tracet "Number of recently opened files: " + f 1 .mruRecentFi 1 eLi st . 1 ength ) ; 
for (i = 0; i < fl .mruRecentFi 1 eLi st . 1 ength ; i++) f 1 . tracet "fi 1 e : " + 
fl .mruRecentFileList[i]); 
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fl.mruRecentFileListType 

Availability 

Flash MX 2004. 
Usage 

fl . mruRecent Fi 1 eLi stType 
Description 

Read-only property; an array of the file types in the MRU list that the authoring tool manages. 
This array corresponds to the array in the fl .mruRecentFileList property. 

Example 

The following example displays the number of recently opened files, and the type of each file, in 
the Output panel. 

fl . trace( "Number of recently opened files: " + 

fl .mruRecentFileLi stfype .length) ; 
for (i = 0; i < fl .mruRecentFi 1 eLi stfype . 1 ength ; i++) fl .trace( "type: " + 

fl .mruRecentFileListfype[i]) ; 

fl.openDocument() 

Availability 

Flash MX 2004. 
Usage 

f 1 . openDocument ( fileURI ) 
Parameters 

fi 1 eURI A string that specifies the name of the file to be opened, expressed as a URI (file:/// 
URI). 

Returns 

If successful, returns the Document object for the newly opened document. If the file is not 
found, or is not a valid FLA file, an error is reported and the script is cancelled. 

Description 

Method; opens a Flash document (FLA file) for editing in a new Flash Document window and 
gives it the focus. For a user, the effect is the same as selecting File > Open and then selecting a 
file. If the specified file is already open, the window that contains the document comes to the 
front. The window that contains the specified file becomes the currently selected document. 



flash object 173 



Example 

The following example opens a file named Document. fla that is stored in the root directory of 
the C drive, stores a Document object representing that document in the doc variable, and sets 
the document to be the currently selected document. That is, until focus is changed, 
fl . getDocumentDOM( ) refers to this document. 

var doc = f 1 . openDocument ( "fi 1 e : ///c | /Document . fl a ") ; 

fl.openProject() 

Availability 

Flash MX 2004. 
Usage 

fl .openProject( fileURI ) 
Parameters 

fi leURI A string that specifies the path of the Flash project file to open, expressed as a URI 
(file:///URI). 

Returns 

Nothing. 
Description 

Method; opens a Flash Project (FLP) file in the authoring tool for editing. 
Example 

The following example opens a project file named myProjectFile.flp that is stored in the root 
directory of the C drive. 

f 1 . open Project ( "f i 1 e : 1 1 1 z | /my Project Fi 1 e . f 1 p" ) ; 

fl.openScript() 

Availability 

Flash MX 2004. 
Usage 

fl .openScripU fi leURI ) 
Parameters 

fi 1 elJRI A string that specifies the path of the JSFL, AS, ASC, XML, TXT or other file that 
should be loaded into the Flash text editor, expressed as a URI (file: ///URI). 

Returns 

Nothing. 
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Description 

Method; opens a script (JSFL, AS, ASC) or other file (XML, TXT) in the Flash text editor. 
Example 

The following example opens a file named my_test.jsfi that is stored in the /temp directory of 
the C drive. 

fl .openScript("file:///c| /temp/my_test . j sf 1 " ) ; 

fl.outputPanel 

Availability 

Flash MX 2004. 

Usage 

f 1 . outputPanel 

Description 

Read-only property; reference to the outputPanel object. 
Example 

See outputPanel object. 

fl.quit() 

Availability 

Flash MX 2004. 
Usage 

fl. quite [bPromptlfNeeded] ) 
Parameters 

bPromptlf Needed A Boolean value that is true (default) if you want the user to be prompted to 
save any modified documents. Set this parameter to false if you do not want the user to be 
prompted to save modified documents. In the latter case, any modifications in open documents 
will be discarded and the application will exit immediately. Although it is useful for batch 
processing, use this method with caution. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; quits Flash, prompting the user to save any changed documents. 
Example 

The following example illustrates quitting with and without asking to save modified documents. 

//quit with prompt to save any modified documents 
fl .quit(); 
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f 1 . qui t ( true ) ; // true is optional 
//quit without saving any files 
f 1 . qui t ( f al se ) ; 

fl.reloadEffects() 

Availability 

Flash MX 2004. 

Usage 

f 1 . rel oadEf f ects ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; reloads all effects descriptors defined in the user's Configuration Effects folder. This 
permits you to rapidly change the scripts during development, and it provides a mechanism to 
improve the effects without relaunching the application. This method works best if used in a 
command placed in the Commands folder. 

Example 

The following example is a one-line script that you can place in the Commands folder. When you 
need to reload effects, go to the Commands menu and execute the script. 

f 1 . rel oadEf f ects ( ) ; 

fl.reloadTools() 

Availability 

Flash MX 2004. 

Usage 

f 1 . rel oadTool s ( ) 

Parameters 

None. 
Returns 

Nothing. 

Description 

Method; rebuilds the toolbar from the toolconfig.xml file. This method is used only when 
creating extensible tools. 
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Example 

The following example is a one-line script that you can place in the Commands folder. When you 
need to reload the toolbar, go to the Commands menu and execute the script. 

f 1 . rel oadTool s ( ) ; 

fl.revertDocument() 

Availability 

Flash MX 2004. 
Usage 

f 1 . revertDocument ( documentObject ) 
Parameters 

documentObject A Document object. If documentObject refers to the active document, the 
Document window might not revert until the script that calls this method finishes executing. 

Returns 

A Boolean value: returns true if the Revert operation completes successfully; f al se otherwise. 
Description 

Method; reverts the specified FLA document to its last saved version. Unlike the File > Revert 
menu option, this method does not display a warning window that asks the user to confirm the 
operation. See also document . revert ( ) and document, can Re vert ( ). 

Example 

The following example reverts the current FLA document to its last saved version; any changes 
made since the last save are lost. 

f 1 . revertDocument ( f 1 . get Document DOM ( ) ) ; 

fl.runScript() 

Availability 

Flash MX 2004. 
Usage 

fl . runScript( fileURI [, funcName [, argl, argZ, ...] ]) 
Parameters 

f f leURI A string that specifies the name of the script file to execute, expressed as a URI (file:/// 
URI). 

funcName A string that identifies a function to execute in the JSFL file that is specified in 
fi 1 eURI. This parameter is optional. 

arg An optional parameter that specifies one or more arguments to be passed to funcname. 
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Returns 

If funcName is specified, returns the function's result as a string. Otherwise, nothing is returned. 
Description 

Method; executes a JavaScript file. If a function is specified as one of the arguments, it runs the 
function and also any code in the script that is not within the function. The rest of the code in the 
script runs before the function is run. 

Example 

Suppose there is a script file named testScript.jsfl in drive C: and its contents are as follows: 

function testFunct(num, minNum) { 

f 1 . tracet " i n testFunct: 1st arg: " + num + " 2nd arg: " + minNum); 

( 

for (i=0; i<2; i++) j 

fl.traceC'in for loop i = " + i); 

I 

f 1 . trace( "end of for loop"); 
//end of testScript.jsfl 

If you issue the following command: 

f 1 . runScri pt ( "f i 1 e : ///C | /testScri pt . j sf 1 " , "testFunct", 10, 1); 

The following information appears in the Output panel: 

in for loop i=0 
in for loop i=l 
end of for loop 

in testFunct: 1st arg: 10 2nd arg: 1 

You can also just call testScript.jsfl without executing a function: 

f 1 . runScri pt( "fi 1 e : ///C | /testScri pt. jsfl ") ; 

which produces the following in the Output panel: 

in for loop i=0 
in for loop i=l 
end of for loop 

fl.saveAIIO 

Availability 

Flash MX 2004. 

Usage 

fl .saveAllO 

Parameters 

None. 
Returns 

Nothing. 
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Description 

Method; saves all open documents, displaying the Save As dialog box for any documents that 
were not previously saved. See also f 1 . saveDocumentAs ( ), f 1 . saveDocument( ), 
document . save ( ), and document . saveAndCompact ( ). 

Example 

The following example saves all open documents. 

fl .saveAl 1 ( ) ; 

fl.saveDocument() 

Availability 

Flash MX 2004. 
Usage 

f 1 . saveDocument( document [, fileURI] ) 
Parameters 

document A Document object that specifies the document to be saved. If document is nul 1 , the 
active document is saved. 

fi leURI A string that specifies the name of the saved document, expressed as a file:///URI. If 
the fileURI parameter is nul 1 or omitted, the document is saved with its current name. If the 
document is not yet saved, Flash displays the Save As dialog box. This parameter is optional. 

Returns 

A Boolean value: true if the save operation completes successfully; f al se otherwise. 
Description 

Method; saves the specified document as a FLA document. See also fl .saveDocumentAsO, 
f 1 . saveAl 1 ( ), document . save( ), and document . saveAndCompact ( ). 

Example 

The following example saves the current document and two specified documents. 

//save the current document 

al ert ( f 1 . saveDocument ( f 1 . get Document DOM ( ) ) ) ; 

//save the specified documents 

al ert ( f 1 . saveDocument ( fl . documents [0] , "file:///C|/examplel.fla")); 
al ert ( f 1 . saveDocument ( fl . documents [1] ,"file:///C|/example2.fla")); 

fl.saveDocumentAs() 

Availability 

Flash MX 2004. 
Usage 

fl . saveDocumentAs ( document ) 
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Parameters 

document A Document object that specifies the document to save. If document is nul 1 , the 
active document is saved. 

Returns 

A Boolean value: true if the Save As operation completes successfully; f al se otherwise. 
Description 

Method; displays the Save As dialog box for the specified document. See also 

f 1 . saveDocument ( ), f 1 . saveAl 1 ( ), document . sa ve( ), and document . saveAndCompact ( ). 

Example 

The following example prompts the user to save the specified document, and then displays a value 
of true or f al se in the Output panel, indicating whether the document was saved. 

al ert ( f 1 . saveDocument As ( f 1 . documents [0] ) ) ; 

fl.setActiveWindow() 

Availability 

Flash MX 2004. 
Usage 

f 1 . setActi veWi ndow( document [, bActi vateFrame^ ) 
Parameters 

document A Document object that specifies the document to select as the active window. 

bAct i vateFrame An optional parameter that is present for consistency with the Dreamweaver 
API. As in Fireworks, it is optional and it is ignored. 

Returns 

Nothing. 
Description 

Method; sets the active window to be the specified document. This method is also supported by 
Dreamweaver and Fireworks. If the document has multiple views (created by Edit In New 
Window), the first view is selected. 

Example 

The following example shows two ways to save a specified document. 

fl . setActi veWi ndow( fl . documents [0] ) ; 

var thelndex = f 1 . f i ndDocument Index( "my Fi 1 e . f 1 a " ) ; 
f 1 . setActi veWi ndow( f 1 . documents [thelndex] ) ; 
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fl.tools 

Availability 

Flash MX 2004. 

Usage 

f 1 . tool s 

Description 

Read-only property; an array of Tools objects (see Tools object). This property is used only when 
creating extensible tools. 

fl.trace() 

Availability 

Flash MX 2004. 

Usage 

f 1 . trace( message ) 

Parameters 

message A string that appears in the Output panel. 
Returns 

Nothing. 
Description 

Method; sends a text string to the Output panel. This method works in the same way as 
outputPanel .tracet ) and the trace( ) statement in ActionScript. 

Example 

The following example displays text in the Output panel. 

fl .tracet "hel lo World! ! ! " ) ; 
var myPet = "cat" ; 
fl.trace("I have a " + myPet); 

fl.version 

Availability 

Flash MX 2004. 

Usage 

f 1 . versi on 

Description 

Read-only property; returns the long string version of the Flash authoring tool, including 
platform. 
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Example 

The following example displays the version of the authoring tool in the Output panel. 

alertt f 1 . version ); // e.g. WIN 7,0,0,380 

fl.xmlui 

Availability 

Flash MX 2004. 

Usage 

f 1 . xml ui 

Description 

Read-only property; an XMLUI object. This property lets you get and set XMLUI properties in a 
XMLUI dialog box and lets you accept or cancel the dialog box programmatically. 

Example 

See XMLUI object. 
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folderltem object 

Inheritance Item object > folderltem object 
Availability 

Flash MX 2004. 
Description 

The folderltem object is a subclass of the Item object. There are no unique methods or properties 
of folderltem. 
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fontltem object 

Inheritance Item object > fontltem object 
Availability 

Flash MX 2004. 
Description 

The fontltem object is a subclass of the Item object. There are no unique methods or properties of 
fontltem. 
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Frame object 

Availability 

Flash MX 2004. 
Description 

The Frame object represents frames in the layer. 

Property summary for the Frame object 

The following properties can be used with the Frame object: 



Property Description 



frame, acti onScri pt Property; a string representing ActionScript code. 

frame. duration Read-only; an integer that represents the number of frames in a 

frame sequence. 

frame, el ements Read-only; an array of Element objects (see Element object). 

frame. 1 abel fype Property; a string that specifies the type of Frame name. 

f rame.moti onTweenOri entf oPath Property; a Boolean value; specifies whether the tweened 

element rotates the element as it moves along a path to 
maintain its angle with respect to each point on the path (true) 
or whether it does not rotate (fal se). 

f rame.moti onTween Rot ate Property; a string that specifies how the tweened element 

rotates. 

f rame.moti onTween Rota teTimes Property; an integer that specifies the number of times the 

tweened element rotates between the starting keyframe and 
the next keyframe. 

f rame.moti onTweenScal e Property; a Boolean value; specifies whether the tweened 

element scales to the size of the object in the following 
keyframe, increasing its size with each frame in thetween (true) 
or doesn't scale (fal se). 

f rame.moti onTween Snap Property; a Boolean value; specifies whether the tweened 

element automatically snaps to the nearest point on the motion 
guide layer associated with this frame's layer (true) or not 
(fal se). 

f rame.moti onTween Sync Property; a Boolean value; if set to true, synchronizes the 

animation of the tweened object with the main Timeline. 

frame . name Property; a string that specifies the name of the frame. 

frame. shapeTweenBl end Property; a string that specifies how a shape tween is blended 

between the shape in the keyframe at the start of the tween and 
the shape in the following keyframe. 

f rame. soundEffect Property; a string that specifies effects for a sound that is 

attached directly to a frame (f rame . sound Li braryltem). 
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Property 



Description 



frame. sound Li bra ry Item 



Property; a library item (see Soundltem object) used to create a 
sound. 



frame . soundLoop 



Property; an integer value that specifies the number of times a 
sound that is attached directly to a frame 

(f rame . sound Li bra ry Item) plays. 



frame . soundLoopMo 



de 



Property; a string that specifies whether a sound that is 
attached directly to a frame (frame . sound Li bra ry I tern) should 
play a specific number of times or loop indefinitely. 



frame . soundName 



Property; a string that specifies the name of a sound that is 
attached directly to a frame (f rame . sound Li braryltem), as 
stored in the library. 



frame . soundSync 



Property; a string that specifies the sync behavior of a sound 
that is attached directly to a frame (frame .sound Li braryltem). 



frame . start Frame 



Read-only; the index of the first frame in a sequence. 



frame . tweenEasi ng 



Property; an integer that specifies the amount of easing that 
should be applied to the tweened object. 



frame . tweenType 



Property; a string that specifies the type of tween; valid values 
are "motion" , "shape" , or "none". 



frame.actionScript 

Availability 

Flash MX 2004. 

Usage 

frame . acti onScri pt 

Description 

Property; a string representing ActionScript code. 
Example 

The following example assigns stop ( ) to first frame top layer action: 

fl . get Document DOM ( ) .getTimel i net ).l ay ers[0] . frame s[0] . act ionScript = 
' stopt ) ; ' ; 

frame.duration 

Availability 

Flash MX 2004. 

Usage 

frame . durati on 
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Description 

Read-only property; an integer that represents the number of frames in a frame sequence. 
Example 

The following example stores the number of frames in a frame sequence that starts at first frame 
in the top layer in the frame Span variable: 

var frameSpan = 

f 1 . ge t Document DOM ( ). getT i me 1 i net). 1 ay ers [0] . frame s [0] . duration; 

frame.elements 

Availability 

Flash MX 2004. 

Usage 

frame . el ements 

Description 

Read-only property; an array of Element objects (see Element object). The order of elements is 
the order in which they are stored in the FLA file. If there are multiple shapes on the Stage, and 
each is ungrouped, Flash treats them as one element. If each shape is grouped, so there are 
multiple groups on the Stage, Flash sees them as separate elements. In other words, Flash treats 
raw, ungrouped shapes as a single element, regardless of how many separate shapes are on the 
Stage. If a frame contains three raw, ungrouped shapes, for example, then el ements .length in 
that frame returns a value of 1 . Select each shape individually, and group it to work around this 
issue. 

Example 

The following example stores an array of current elements on the top layer, first frame in the 
my Elements variable: 

var myElements = 

f 1 . ge t Document DOM ( ) . getTimel i ne ( ) . 1 ayers [0] . frames [0] .el ements ; 

frame.labelType 

Availability 

Flash MX 2004. 

Usage 

frame . 1 abel fype 

Description 

Property; a string that specifies the type of Frame name. Valid values are "none", "name", 
"comment", and "anchor". Setting a label to "none" clears the frame . name property. 
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Example 

The following example sets the name of the first frame in the top layer to " Fi rst Frame " and 
then sets its label to "comment": 

fl . getDocumentDOM( ) .getTimel ine( ) .1 ayers[0] .frames[0] .name = 'First Frame'; 
f 1 . get Document DOM ( ). getT i me lineU.l ay ers [0] . frame s [0] . label Type = ' comment ' ; 

frame. motionTweenOrientToPath 

Availability 

Flash MX 2004. 
Usage 

frame. mo tionTweenOrient To Path 
Description 

Property; a Boolean value; specifies whether the tweened element rotates the element as it moves 
along a path to maintain its angle with respect to each point on the path (true) or whether it does 
not rotate (f al se). 

If you want to specify a value for this property, you should set frame . moti onTweenRotate to 
"none". 

frame.motionTweenRotate 

Availability 

Flash MX 2004. 
Usage 

f rame . moti onTweenRotate 
Description 

Property; a string that specifies how the tweened element rotates. Acceptable values are "none", 
"auto", "cl ockwi se", and "counter-clockwise". A value of "auto" means the object will 
rotate in the direction requiring the least motion to match the rotation of the object in the 
following keyframe. 

If you want to specify a value for frame . moti onTweenOri entToPath, set this property to 
"none". 

Example 

See frame .moti onTweenRotateTimes. 
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frame. motionTweenRotateTimes 

Availability 

Flash MX 2004. 
Usage 

f rame . moti onTweenRotateTimes 
Description 

Property; an integer that specifies the number of times the tweened element rotates between the 
starting keyframe and the next keyframe. 

Example 

The following example rotates the element in this frame counter-clockwise three times by the 
time it reaches the next keyframe: 

fl . getDocumentDOM( ) .getTimel ine( ) .1 ayers[0] . frame s[0] .moti onTween Rot ate = 

" counter-cl ockwi se" ; 
fl . getDocumentDOMt ) .getTimel ine( ) .1 ayers[0] . frame s[0] .motionTweenRotateTimes = 

3; 

frame.motionTweenScale 

Availability 

Flash MX 2004. 
Usage 

frame. moti on TweenScale 
Description 

Property; a Boolean value; specifies whether the tweened element scales to the size of the object in 
the following keyframe, increasing its size with each frame in the tween (true) or doesn't scale 

(fal se). 

frame.motionTweenSnap 

Availability 

Flash MX 2004. 

Usage 

frame. mo tionTweenSnap 

Description 

Property; a Boolean value; specifies whether the tweened element automatically snaps to the 
nearest point on the motion guide layer associated with this frame's layer (true) or not (fal se). 
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frame.motionTweenSync 

Availability 

Flash MX 2004. 

Usage 

f rame . mot i onTween Sync 

Description 

Property; a Boolean value; if set to true, synchronizes the animation of the tweened object with 
the main Timeline. 

Example 

The following example specifies that tweened object should be synchronized with the Timeline: 

fl . get Document DOM ( ).getTimeline().layers[0].frames[0] . mo ti onTween Sync = true; 

frame. name 
Availability 

Flash MX 2004. 

Usage 

frame . name 

Description 

Property; a string that specifies the name of the frame. 
Example 

The following example sets the name of the first frame, top layer to " Fi rst Frame " and then 
stores the name value in the f rameLabel variable: 

fl . getDocumentDOM( ) .getTimel ine( ) .1 ayers[0] .frames[0] .name = 'First Frame'; 
var frameLabel = fl . getDocumentDOM( ). getTi mel i ne( ). 1 ayers [0] . frames [0] . name ; 

frame.shapeTweenBlend 

Availability 

Flash MX 2004. 

Usage 

frame . shapeTweenBl end 

Description 

Property; a string that specifies how a shape tween is blended between the shape in the keyframe 
at the start of the tween and the shape in the following keyframe. Valid values are 
"di stri buti ve" and "angular". 
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frame.sound Effect 

Availability 

Flash MX 2004. 

Usage 

frame . soundEf f ect 

Description 

Property; a string that specifies effects for a sound that is attached directly to a frame 
(frame . soundLi bra ry I tern). Acceptable values are "none", "left channel", "right 
channel ", "fade left to right", "fade right to left", "fade in", "fade out", and 
"custom". 

Example 

The following example specifies that the sound attached to the first frame should fade in: 

fl . getDocumentDOM( ) .getfimel ine( ) .1 ayers[0] .frames[0] .soundEffect = "fade in"; 

frame.soundLibraryltem 

Availability 

Flash MX 2004. 
Usage 

frame. soundLi bra ry It em 
Description 

Property; a library item (see Soundltem object) used to create a sound. The sound is attached 
directly to the frame. 

Example 

The following example assigns the first item in the library (which must be a sound object) to the 
soundLi bra ry Item property of the first frame: 

fl . get Document DOM ( ). getf i me 1 i net ).l ay ers[0] . frame s[0] . soundLi bra ry It em 
=f 1 . get Document DOM ( ) . 1 i brary . i terns [0] ; 

frame.soundLoop 

Availability 

Flash MX 2004. 

Usage 

frame.soundLoop 
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Description 

Property; an integer value that specifies the number of times a sound that is attached directly to a 
frame (frame. soundLibrary Item) plays. If you want to specify a value for this property, set 

frame. soundLoopMode to "repeat". 

Example 

See frame . soundLoopMode. 

frame.soundLoopMode 

Availability 

Flash MX 2004. 

Usage 

frame. soundLoopMode 

Description 

Property; a string that specifies whether a sound that is attached directly to a frame 
(frame.soundLibraryltem) should play a specific number of times or loop indefinitely. Valid 
values are "repeat " and "loop". To specify the number of times the sound should play, set a 
value for frame . soundLoop. 

Example 

The following example specifies that a sound should play two times: 

f 1 . ge t Document DOM ( ) . getTi me 1 i net). layers[0]. frame s [0] . soundLoopMode = 
" repeat" ; 

f 1 . ge t Document DOM ( ). getTi me 1 i net). layers[0]. frame s [0] . sound Loop = 2; 

frame.soundName 

Availability 

Flash MX 2004. 

Usage 

frame . soundName 

Description 

Property; a string that specifies the name of a sound that is attached directly to a frame 
(frame.soundLibra ry I tern), as stored in the library. 

Example 

The following example changes the soundName property of the first frame to " songl . mp3"; 
songl.mp3 must exist in the library: 

f 1 . get Document DOM ( ). getf i me li net). 1 ay ers [0] . frame s [0] . soundName = " songl . mp3" ; 
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frame.soundSync 



Availability 

Flash MX 2004. 

Usage 

frame . soundSync 

Description 

Property; a string that specifies the sync behavior of a sound that is attached directly to a frame 
(frame.soundLibra ry I tern). Acceptable values are "event", "stop", "start", and "stream". 

Example 

The following example specifies that a sound should stream: 

f 1 . get Document DOM ( ). getT i me lineU.l ay ers [0] . frame s [0] . sound Sync = 'stream'; 

frame.startFrame 

Availability 

Flash MX 2004. 

Usage 

frame.startFrame 

Description 

Read-only property; the index of the first frame in a sequence. 
Example 

In the following example, stFrame is the index of the first frame in the frame sequence. In this 
example, a frame sequence is spanning the six frames from Frame 5 to Frame 10. Therefore, the 
value of stFrame at any frame between Frame 5 and Frame 10 is 4 (remember that index values 
are different from frame number values). 

var stFrame = 

fl . get Document DOM ( ) . getf imel ine( ) .1 ayers[0] . frame s[4] .startFrame; 
fl . trace( stFrame ) ; // 4 
var stFrame = 

f 1 . get Document DOM ( ) . getTimel ine( ) .1 ayers[0] . frame s [9] .startFrame; 
fl . tracet stFrame ) ; // 4 

frame.tweenEasing 

Availability 

Flash MX 2004. 

Usage 

frame.tweenEasing 
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Description 

Property; an integer that specifies the amount of easing that should be applied to the tweened 
object. Valid values are -100 to 100. To begin the motion tween slowly and accelerate the tween 
toward the end of the animation, use a value between -1 and -100. To begin the motion tween 
rapidly and decelerate the tween toward the end of the animation, use a positive value between 1 
and 100. 

Example 

The following example specifies that the motion of the tweened object should begin fairly rapidly 
and decelerate toward the end of the animation: 

fl . getDocumentD0M( ) .getTimel i ne( ) .1 avers [0] .f ramesCO] .tween Easing = 50; 
frame.tweenType 

Availability 

Flash MX 2004. 

Usage 

frame . tweenType 

Description 

Property; a string that specifies the type of tween; valid values are "motion", "shape", or "none". 
The value "none" removes the motion tween. Use the timel i ne . createMoti onTween ( ) 
method to create a tween. 

If you specify "moti on", the object in the frame must be a symbol, text field, or grouped object. It 
will be tweened from its location in the current keyframe to the location in the following 
keyframe. 

If you specify "shape", the object in the frame must be a shape. It will blend from its shape in the 
current keyframe to the shape in the following keyframe. 

Example 

The following example specifies that the object is a motion tween, and therefore, it should be 
tweened from its location in the current keyframe to the location in the following keyframe: 

fl . get Document DOM ( ) .getTimel i ne( ) .1 aye rs[0] . frames [0] .tweenType = "motion" ; 



194 Chapter 3: Objects 



HalfEdge object 



Availability 

Flash MX 2004. 
Description 

The halffidge object is the directed side of the edge of a Shape object. An edge has two half edges. 
You can transverse the contours of a shape by "walking around" these half edges. For example, 
starting from a half edge, you can visit all the half edges around a contour of a shape, and return 
to the original half edge. 

Half edges are ordered. One half edge represents one side of the edge; the other half edge 
represents the other side. 

Method summary for the HalfEdge object 

The following methods are available for the halffidge object: 
Method Description 

ha 1 f Edge, get Edge ( ) Gets the Edge object for the half Edge object. 

hal f Edge . get Next ( ) Gets the next half edge on the current contour. 

hal f Edge . getOpposi teHal f Edge( ) Gets the half Edge object on the other side of the edge. 

hal f Edge, get Prev( ) Gets the preceding half Edge object on the current contour. 

hal f Edge . get Vert ex ( ) Gets the Vertex object at the head of the half Edge object. 



Property summary for the HalfEdge object 

The following properties are available for the halffidge object: 



Property 


Description 


hal f Edge . i d 


Read-only; a unique integer identifier for the halfEdge object. 



half Edge. getEdge() 
Availability 

Flash MX 2004. 

Usage 

hal f Edge . getEdge( ) 

Parameters 

None. 
Returns 

An Edge object. 
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Description 

Method; gets the Edge object for the halfEdge object. 
Example 

The following example illustrates getting an edge and a half edge for the specified shape. 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
var halfEdge = shape. edges[0] .getHal fEdge(O) ; 
var edge = hal f Edge . getEdge ( ) ; 

half Edge. getNext() 

Availability 

Flash MX 2004. 

Usage 

hal f Edge . getNext ( ) 

Parameters 

None. 
Returns 

A halfEdge object. 
Description 

Method; gets the next half edge on the current contour. 
Note: Although half edges have a direction and a sequence order, edges do not. 
Example 

The following example stores the next half edge of the specified contour in the nextHal f Edge 
variable: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
var hEdge = shape. edges[0] .getHal fEdge( 0 ); 
var nextHalfEdge = hEdge. getNext( ) ; 

half Edge. getOppositeHalfEdge() 

Availability 

Flash MX 2004. 
Usage 

hal f Edge . getOpposi teHalfEdgeO 
Parameters 

None. 
Returns 

A halfEdge object. 
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Description 

Method; gets the halffidge object on the other side of the edge. 
Example 

The following example stores the half edge opposite hEdge in the otherHal f Edge variable: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 

var hEdge = shape. edges[0] .getHal fEdge(O) ; 

var otherHal f Edge = hEdge . getOpposi teHal fEdge( ) ; 

half Edge. getPrev() 

Availability 

Flash MX 2004. 

Usage 

hal f Edge . getPrev ( ) 

Parameters 

None. 
Returns 

A halffidge object. 
Description 

Method; gets the preceding halffidge object on the current contour. 
Note: Although half edges have a direction and a sequence order, edges do not. 
Example 

The following example stores the previous half edge of the specified contour in the 

prevHal f Edge variable: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
var hEdge = shape. edges[0] .getHal fEdge( 0 ); 
var prevHalfEdge = hEdge . getPrev( ) ; 

half Edge. getVertex() 

Availability 

Flash MX 2004. 

Usage 

hal f Edge . getVertext ) 

Parameters 

None. 
Returns 

A Vertex object. 
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Description 

Method; gets the Vertex object at the head of the halfEdge object. 
Example 

The following example stores the Vertex object at the head of hEdge in the vertex variable: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 

var edge = shape. edges[0] ; 

var hEdge = edge . getHal f Edge( 0 ) ; 

var vertex = hEdge . getVertext ) ; 

halfEdge. id 

Availability 

Flash MX 2004. 

Usage 

hal f Edge. id 

Description 

Read-only property; a unique integer identifier for the halfEdge object. 
Example 

The following example displays a unique identifier for the specified half edge in the Output 
panel: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
alert(shape.contours[0] .getHalfEdge( ) .id) ; 



198 Chapter 3: Objects 



Instance object 

Inheritance Element object > Instance object 
Availability 

Flash MX 2004. 
Description 

Instance is a subclass of the Element object. 

Property summary for the Instance object 

In addition to all of the Element object properties, Instance has the following properties: 
Property Description 

instance, i nstanceType Read-only; a string that represents the type of Instance, 
instance.libraryltem Library item used to instantiate this instance. 

instance. instanceType 

Availability 

Flash MX 2004. 

Usage 

instance.!' nstanceType 

Description 

Read-only property; a string that represents the type of Instance. Valid values are "symbol ", 
"bi tmap", "embedded vi deo", "1 i nked vi deo", and "compi 1 ed clip". 

Example 

The following example shows that the instance type of a movie clip is "symbol " : 

//select a movie clip, then run this script 

var type = fl . getDocumentDOM( ). sel ecti on [0] . i nstanceType ; 

Tl . trace( "Thi s instance type is " + type); 

instance.libraryltem 

Availability 

Flash MX 2004. 

Usage 

instance.libraryltem 

Description 

Property; a library item used to instantiate this instance. You can change this property only to 
another library item of the same type (that is, you cannot set a symbol instance to refer to a 
bitmap). See library object. 
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Example 

The following example changes the selected symbol to refer to the first item in the library: 

f 1 . ge t Document DOM ( ) . sel ecti on[0] . 1 i braryltem = 
f 1 . ge t Document DOM ( ) . 1 i brary . i terns [0] ; 
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Item object 

Availability 

Flash MX 2004. 
Description 

The Item object is an abstract base class. Anything in the library derives from Item. See also 
library object. 

Method summary for the Item object 

The following methods are available for the Item object. 

Method Description 

i tern. addData( ) Method; adds specified data to a library item. 

i tern . getData ( ) Method; retrieves the value of the specified data. 

i tem.hasDataO Method; determines whether the library item has the named data. 

item. removeData( ) Method; removes persistent data from the library item. 

Property summary for the Item object 

The following properties are available for the Item object. 
Property Description 

i tern . i temType Read-only; a string that specifies the type of element. 

item.l i nkageCl ass Name Property; a string that specifies the ActionScript 2.0 class that 

will be associated with the symbol. 

i tern. 1 i nkage Export For AS Property; a Boolean value. If true, the item is exported for 

ActionScript. 

i t em. 1 i nkage Export For RS Property; a Boolean value. If true, the item is exported for 

runtime sharing. 

item. 1 i nkage Expo rtlnFi rstFrame Property; a Boolean value. If true, the item is exported in the first 

frame. 

item. 1 i nkage I dent i f ier Property; a string that specifies the name Flash will use to identify 

the asset when linking to the destination SWF file. 

item. 1 i nkage Import For RS Property; a Boolean value. If true, the item is imported for 

runtime sharing. 

i tern. 1 i nkageURL Property; a string that specifies the URL where the SWF file 

containing the shared asset is located. 

i tern . name Property; a string that specifies the name of the library item, 

which includes the folder structure. 
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item.addData() 

Availability 

Flash MX 2004. 
Usage 

i tern . addData ( name, type, data ) 
Parameters 

name A string that specifies the name of the data. 

typ e A string that specifies the type of data. Valid types are "integer", " i n t e g e r A r r a y " , 
"double", "doubl eArray ", "string", and "byteArray". 

data The data to add to the specified library item. The type of data depends on the value of the 
type parameter. For example, if type is "integer", the value of data must be an integer, and so on. 

Returns 

Nothing. 
Description 

Method; adds specified data to a library item. 
Example 

The following example adds data named myData with an integer value of 12 to the first item in 
the library: 

f 1 . get Document DOM ( ) . 1 i brary . i terns [0] .addData( "myData", "integer", 12); 

item.getData() 

Availability 

Flash MX 2004. 

Usage 

i tern . getData ( name ) 

Parameters 

name A string that specifies the name of the data to retrieve. 
Returns 

The data specified by the name parameter. The type of data returned depends on the type of 
stored data. 

Description 

Method; retrieves the value of the specified data. 
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Example 

The following example gets the value of the data named myData from the first item in the library 
and stores it in the variable 1 i bData. 

var 1 i bData = fl . getDocumentDOM( ). 1 i brary . i terns [0] . getData ( "myData" ); 

item.hasData() 

Availability 

Flash MX 2004. 

Usage 

i tern . hasData ( name ) 

Parameters 

name A string that specifies the name of the data to check for in the library item. 
Returns 

A Boolean value: true if the specified data exists; false otherwise. 
Description 

Method; determines whether the library item has the named data. 
Example 

The following example shows a message in the Output panel if the first item in the library 
contains data point named myData: 

if ( fl . getDocumentDOM( ). 1 i brary . i tems[0] . hasData( "myData" ) )( 
f 1 . tracet "Yep , it's there!"); 

I 

item.itemType 

Availability 

Flash MX 2004. 

Usage 

i tern . i temType 

Description 

Read-only property; a string that specifies the type of element. Potential values are " undef i ned", 
"component", "movi e clip", "graphic", "button", "video", "f ol der ", "font", "sound", 
"bi tmap", "compi led clip", and "video". 

Example 

The following example shows the type of the specified library item in the Output panel: 

fl .trace(fl . ge t Document DOM ( ) . 1 i brary . i terns [0] . i temType ) ; 



Item object 203 



item.linkageClassName 

Availability 

Flash MX 2004. 

Usage 

i tern . 1 i nkageCl assName 

Description 

Property; a string that specifies the ActionScript 2.0 class that will be associated with the symbol. 
For this property to be defined, the i tern . 1 i nkage Export For AS and/or 

i tern. 1 i nkage Export ForRS properties must be set to true, and the item.l i nkage Import ForRS 
property must be set to fal se. 

Example 

The following example specifies that the ActionScript 2.0 class name associated with the first item 
in the Library is myClass: 

f 1 . ge t Document DOM ( ) . 1 i bra ry . i terns [0] .linkageClassName = "my Class"; 

item.linkageExportForAS 

Availability 

Flash MX 2004. 
Usage 

i tern . 1 i nkage Export For AS 
Description 

Property; a Boolean value. If true, the item is exported for ActionScript. You can also set the 

it em. linkage Export ForRS and item.linkageExportlnFirstFrame properties to true. The 
i tern. 1 i nkagelmportForRS property must be set to fal se if this property is set to true. 

Example 

The following example sets this property for the specified library item: 

f 1 . ge t Document DOM ( ) . 1 i bra ry . i terns [0] . 1 i nkage Export For AS = true ; 

item.linkageExportForRS 

Availability 

Flash MX 2004. 
Usage 

i tern . 1 i nkage Export ForRS 
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Description 

Property; a Boolean value. If t r u e , the item is exported for runtime sharing. This property can be 
set to true only if i tern . 1 i nkage Import ForRS is set to f al se. Also, the properties 
i tern. 1 i n ka gel dent i f i er and i tem . 1 i nkageURL must be defined. 

Example 

The following example sets this property for the specified library item: 

f 1 . ge t Document DOM ( ) . 1 i bra ry . i terns [0] . linkage ExportForRS = true; 

item.linkageExportlnFirstFrame 

Availability 

Flash MX 2004. 
Usage 

i tem. li nkage Export InFirstFrame 
Description 

Property; a Boolean value. If true, the item is exported in the first frame; if f al se, the item is 
exported on the frame of the first instance. If the item does not appear on the Stage, it isn't 
exported. 

This property can be set to true only when i tem. 1 i nkage Export For AS and/or 
i tem. 1 i nkage Export ForRS are set to true. 

Example 

The following example specifies that the specified library item is exported in the first frame: 

f 1 . getDocumentDOM( ) . 1 i brary . i terns [0] .li nkage Export InFirstFra me = true; 

item.linkageldentifier 

Availability 

Flash MX 2004. 
Usage 

i tem . 1 i n ka gel dent i f i er 
Description 

Property; a string that specifies the name Flash will use to identify the asset when linking to the 
destination SWF file. It must be specified if i tem. 1 i nkageExportForAS and/or 
i tem. 1 i nkage Export ForRS are set to true. 

Example 

The following example specifies that the string my_mc will be used to identify the library item 
when it is linked to the destination SWF file to which it is being exported: 

f 1 . ge t Document DOM ( ) . 1 i bra ry . i terns [0] .linkageldentifier = "my_mc" ; 
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item.linkagelmportForRS 

Availability 

Flash MX 2004. 
Usage 

i tern . 1 i nkage Import ForRS 
Description 

Property; a Boolean value: if true, the item is imported for runtime sharing. If this property is set 
to true, both i tern. 1 i nkage Export For AS and item.l inkageExport ForRS must be set to 
f al se. Also, you must specify an identiflier (i tern. 1 i n ka gel dent i f i er) and a URL 
(i tern . 1 i nkageURL). 

Example 

The following example sets this property to true for the specified library item: 

f 1 . getDocumentDOM( ) . 1 i brary . i terns [0] . 1 i nkage Import ForRS = true ; 

item.linkageURL 

Availability 

Flash MX 2004. 

Usage 

i tern . 1 i nkageURL 

Description 

Property; a string that specifies the URL where the SWF file containing the shared asset is located. 
Must be set when i tern. 1 i nkage Export ForRS or i tern. 1 i nkage Import ForRS is set to true. You 
can specify a web URL or a file name in platform-dependent format (that is, forward slashes (/) or 
backward slashes (\), depending on the platform). 

Example 

The following example specifies a linkage URL for the specified library item: 

f 1 . ge t Document DOM ( ) . 1 i bra ry . i terns [0] .linkageURL = "theShareSWF.swf"; 

item. name 

Availability 

Flash MX 2004. 

Usage 

i tern. name 
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Description 

Method; a string that specifies the name of the library item, which includes the folder structure. 
For example, if Symbol_l is inside a folder called Folder_l, the name property of Symbol_l is 

" Fol der_l/ Symbol 

Example 

The following example shows the name of the specified library item in the Output panel: 

fl .tracetfl . get Document DOM ( ) . 1 i brary . i tems [0] . name ) ; 

item.removeData() 

Availability 

Flash MX 2004. 
Usage 

i tern . removeData ( name ) 
Parameters 

name Specifies the name of the data to remove from the library item. 
Returns 

Nothing. 
Description 

Property; removes persistent data from the library item. 
Example 

The following example removes the data named myData from the first item in the library: 

f 1 . getDocumentDOM( ) . 1 i brary . i tems [0] . removeData ( "myData " ) ; 
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Layer object 

Availability 

Flash MX 2004. 
Description 

The Layer object represents a layer in the Timeline. The timeline. layers property contains an 
array of Layer objects, which can be accessed by 
fl . getDocumentDOM( ) .getTimel ine( ) .1 ayers. 

Property summary for the Layer object 

The following properties are available for the Layer object: 

Property Description 

1 ayer. col or Property; a string that specifies the color assigned to outline the layer, 

layer. frameCount Read-only; an integer that specifies the number of frames in the layer. 
1 ayer . frames Read-only; an array of Frame objects. 

1 ayer . hei ght Property; an integer that specifies the percentage layer height; equivalent to the 

Layer height value in the Layer Properties dialog box. 

1 ayer . 1 ayerType Property; a string that specifies the current use of the layer; equivalent to the 
Type setting in the Layer Properties dialog box. 

1 ayer. 1 ocked Property; a Boolean value that specifies the locked status of the layer. 

1 ayer . name Property; a string that specifies the name of the layer. 

1 ayer .out! i ne Property; a Boolean value that specifies the status of outlines for all objects on 
the layer. 

1 ayer . pa rent Layer Property; a Layer object that represents the layer's containing folder, guiding, or 
masking layer. 

1 ayer . vi si bl e Property; a Boolean value that specifies whether the layer's objects on the 
Stage are shown or hidden. 

layer.color 

Availability 

Flash MX 2004. 

Usage 

1 ayer . col or 

Description 

Property; a string that specifies the color assigned to outline the layer; equivalent to the Outline 
color setting in the Layer Properties dialog box. Specified in hexadecimal #rrggbb format (where 
r is red, g is green, and b is blue), a hexidecimal color value (such as OxFFOOOO), or an integer 
color value. 
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Example 

The following example stores the value of the first layer in the colorValue variable: 

var colorValue = f 1 . getDocumentDOM( ) . getTi mel i ne( ) . 1 ayers [0] . col or ; 

The following example shows three ways to set the color of the first layer to red: 

fl .get Document DOM ( ) .getTi mel ine( ) .1 ayers [0] .col or=167 11680; 
fl .get Document DOM ( ) .getTi mel ine( ) .1 ayers [0] . col or="#ff 0000" ; 
Tl .get Document DOM ( ) .getTi mel ine( ) .1 ayers [0] . col or=0xFF0000 ; 

layer.frameCount 

Availability 

Flash MX 2004. 

Usage 

1 ayer . f rameCount 

Description 

Read-only property; an integer that specifies the number of frames in the layer. 
Example 

The following example stores the number of frames in the first layer in the TcNum variable: 
var TcNum = Tl . getDocumentD0M( ). getTi mel i ne( ). 1 ayers [0] . TrameCount ; 

layer.frames 

Availability 

Flash MX 2004. 

Usage 

1 ayer . frames 

Description 

Read-only property; an array of Frame objects (see Frame object). 
Example 

The following example sets the variable f rameArray to the array of Frame objects for the frames 
in the current document: 

var TrameArray = Tl . getDocumentDOMt ). getTimel i ne (). 1 ayers [0] . Trames ; 

To determine if a frame is a keyframe, check whether the frame. startFrame property matches 
the array index, as shown in the following example: 

var TrameArray = Tl . getDocumentD0M( ). getTi mel i ne( ). 1 ayers [0] . Trames ; 
var n = TrameArray . 1 ength ; 
Tor (1=0; i<n; i++) { 

if ( i==f rameArray [ i ]. start Frame ) { 
al ert( "Keyframe at: " + i); 
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I 

} 



layer.height 

Availability 

Flash MX 2004. 

Usage 

1 ayer . height 

Description 

Property; an integer that specifies the percentage layer height; equivalent to the Layer height value 
in the Layer Properties dialog box. Acceptable values represent percentages of the default height: 
100, 200, or 300. 

Example 

The following example stores the percentage value of the first layer's height setting: 

var layerHeight = f 1 . getDocumentD0M( ) . getTi mel i ne( ) . 1 ayers [0] . hei ght ; 
The following example sets the height of the first layer to 300 percent: 

fl . getDocumentD0M( ) .getTimel ine( ) .1 ayers[0] .height = 300; 

layer.layerType 

Availability 

Flash MX 2004. 

Usage 

1 ayer . 1 ayerType 

Description 

Property; a string that specifies the current use of the layer; equivalent to the Type setting in the 
Layer Properties dialog box. Acceptable values are "normal", "guide", "guided", "mask", 
"masked", "folder". 

Example 

The following example sets the first layer in the Timeline to type "folder": 

f 1 . get Document DOM ( ). getTimel i ne (). 1 ayers [0] . 1 ayerType = "f ol der " ; 

layer.locked 

Availability 

Flash MX 2004. 

Usage 

1 ayer . 1 ocked 
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Description 

Property; a Boolean value that specifies the locked status of the layer. If set to true, the layer is 
locked. The default value is false. 

Example 

The following example stores the Boolean value for the status of the first layer in the lockStatus 
variable: 

var lockStatus = f 1 . getDocumentDOM( ) . getTi mel i ne( ) . 1 ayers [0] . 1 ocked ; 

The following example sets the status of the first layer to unlocked: 

fl . getDocumentDOMt ). getTimel i ne (). 1 ayers [0] . 1 ocked = false; 

layer.name 

Availability 

Flash MX 2004. 

Usage 

1 ayer . name 

Description 

Property; a string that specifies the name of the layer. 
Example 

The following example sets the name of the first layer in the current document to "foreground": 

fl .getDocumentDOMt ) .getTimel ine( ) .1 ayers [0] .name = "foreground" ; 

layer.outline 

Availability 

Flash MX 2004. 

Usage 

1 ayer . outl i ne 

Description 

Property; a Boolean value that specifies the status of outlines for all objects on the layer. If set to 
true, all objects on the layer appear only with outlines. If f al se, objects appear as they were 
created. 

Example 

The following example makes all objects on the first layer appear only with outlines: 

fl . getDocumentDOMt ). getTimel i ne (). 1 ayers [0] . outl i ne = true; 
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layer.parentLayer 

Availability 

Flash MX 2004. 

Usage 

1 ayer.parentLayer 

Description 

Property; a Layer object that represents the layer's containing folder, guiding, or masking layer. 
Acceptable values for the parent layer are a folder, guide, or mask layer that precedes the layer, or 
the parentLayerof the preceding or following layer. Setting the layer's parentLayer does not 
move the layer's position in the list; trying to set a layer's parentLayer to a layer that would 
require moving it has no effect. Uses null for a top-level layer. 

Example 

The following example uses two layers at the same level on the same Timeline. The first layer 
(layers [0]) is converted into a folder and then set as the parent folder of the second layer 
(layers [1]). This action moves the second layer inside the first layer. 

var parLayer = f 1 . getDocumentDOM( ) . getTimel i ne ( ) . 1 ayers [0] ; 
pa rLayer . 1 ayerType = "folder"; 

f 1 . ge t Document DOM ( ) . getTi me lineU.l ay ers [ 1 ] . parentLayer = parLayer; 

layer.visible 
Availability 

Flash MX 2004. 

Usage 

1 ayer . vi si bl e 

Description 

Property; a Boolean value that specifies whether the layer's objects on the Stage are shown or 
hidden. If set to true, all objects in the layer are visible; if f al se, they are hidden. The default 
value is true. 

Example 

The following example makes all objects in the first layer invisible: 

fl . getDocumentD0M( ). getTimel i ne (). 1 ayers [0] . vi si bl e = false; 
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library object 

Availability 

Flash MX 2004. 
Description 

The library object represents the Library panel. It is a property of the Document object (see 
document . 1 i brary) and can be accessed by f 1 . ge t Document DOM ( ) . 1 i bra ry. 

The library object contains an array of items of different types, including symbols, bitmaps, 
sounds, and video. 

Method summary for the library object 

The following methods are available for the library object: 

Method Description 

i brary . addItemToDocument( ) Method; adds the current or specified item to the Stage at the 

specified position. 

i brary . add New Item ( ) Method; creates a new item of the specified type in the Library panel 

and sets the new item to the currently selected item. 

i brary .del eteltem( ) Method; deletes the current items or a specified item from the 

Library panel. 

ibrary.duplicateltemO Method; makes a copy of the currently selected or specified item. 

ibrary.editltem( ) Method; opens the currently selected or specified item in Edit 

mode. 

i brary . expand Fol der( ) Method; expands or collapses the currently selected or specified 

folder in the library. 

i brary . f i ndltemlndex( ) Method; returns the library item's index value (zero-based). 

ibrary.getltemPropertyt ) Method; gets the property for the selected item. 

i brary . getltemType( ) Method; gets the type of object currently selected or specified by a 

library path. 

i brary . getSel ectedl terns ( ) Method; gets the array of all currently selected items in the library. 

i brary . i mportEmbeddedSWF( ) Method; imports a Shockwave (SWF) file into the library as a 

compiled clip. 

i brary . i temExi sts( ) Method; checks to see if a specified item exists in the library. 

i brary .moveToFol der( ) Method; moves the currently selected or specified library item to a 

specified folder. 

i brary . new Fol der( ) Method; creates a new folder with the specified name, or a default 

name("untitled folder #") if no fol derName parameter is provided, 
in the currently selected folder. 

i brary . rename It em ( ) Method; renames the currently selected library item in the Library 

panel. 
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Method 




Description 


library. 


selectAll ( ) 


Method; selects or deselects all items in the library. 


library. 


sel ectltemt ) 


Method; selects a specified library item. 


1 i brary . 


sel ectNonet ) 


Method; deselects all the library items. 


1 i bra ry . 


setItemProperty( ) 


Method; sets the property for all selected library items (ignoring 
folders). 


1 i bra ry . 


updateltem( ) 


Method; updates the specified item. 



Property summary for the library object 

The following property is available for the library object. 

Property Description 

1 i brary . i terns Property; an array of item objects in the library 

library.addltemToDocument() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary .addltemToDocumentt position [, namePath^ ) 
Parameters 

posit i on A point that specifies the x,y position of the center of the item on the Stage. 

namePath A string that specifies the name of the item. If the item is in a folder, you can specify 
its name and path using slash notation. If namePath is not specified, the current library selection 
is used. This parameter is optional. 

Returns 

A Boolean value: true if the item is successfully added to the document; fal se otherwise. 
Description 

Method; adds the current or specified item to the Stage at the specified position. 
Example 

The following example adds the currently selected item to the Stage at the (3, 60) position: 

f 1 . getDocumentDOM . 1 i brary . a dd I temTo Document ( { x : 3 , y : 60 } ) ; 

The following example adds the item Symbol 1 located in folderl of the library to the Stage at the 
(550, 485) position: 

fl .get Document DOM ( ) . 1 i brary . addltemToDocumentt I x: 550.0, y: 485.0} , "fol derl/ 
Symbol 1 " ) ; 
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library.addNewltem() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary.addNewItem( type [, namePath] ) 
Parameters 

type A string that specifies the type of item to create. The only acceptable values for type are 
"video", "movi e clip", "button ", "graphic", "bi tmap", and "folder" (so, for example, you 
cannot add a sound to the library with this method). Specifying a folder path is the same as using 
1 i bra ry . newFol der ( ) before calling this method. 

namePath A string that specifies the name of the item to be added. If the item is in a folder, 
specify its name and path using slash notation. This parameter is optional. 

Returns 

A Boolean value: true if the item is successfully created; false otherwise. 
Description 

Method; creates a new item of the specified type in the Library panel and sets the new item to the 
currently selected item. 

Example 

The following example creates a new button item named start in a new folder named folderTwo: 

f 1 . get Document DOM ( ) . 1 i bra ry . add New Item ( "button " , "f ol derf wo/sta rt " ) ; 

library.deleteltem() 

Availability 

Flash MX 2004. 
Usage 

1 i brary . del etel tem( [ namePath ] ) 
Parameters 

namePath A string that specifies the name of the item to be deleted. If the item is in a folder, 
you can specify its name and path using slash notation. If you pass a folder name, the folder and 
all its items are deleted. If no name is specified, Flash deletes the currently selected item or items. 
To delete all the items in the Library panel, select all items before using this method. This 
parameter is optional. 

Returns 

A Boolean value: true if the items are successfully deleted; false otherwise. 
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Description 

Method; deletes the current items or a specified item from the Library panel. This method can 
affect multiple items if several are selected. 

Example 

The following example deletes the currently selected item: 

f 1 . ge t Document DOM ( ) . 1 i bra ry . del eteltemt ) ; 

The following example deletes the item Symbol_l from the library folder Folder_l: 

f 1 . get Document DOM ( ) . 1 i brary . del etel tem( " Fol der_l/Symbol_l " ) ; 

library.duplicateltem() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary.dupl icateltem( [ namePath ] ) 
Parameters 

namePath A string that specifies the name of the item to duplicate. If the item is in a folder, you 
can specify its name and path using slash notation. This parameter is optional. 

Returns 

A Boolean value: true if the item is duplicated successfully; false otherwise. If more than one 
item is selected, Flash returns fal se. 

Description 

Method; makes a copy of the currently selected or specified item. The new item has a default 
name (such as i tern copy) and is set as the currently selected item. If more than one item is 
selected, the command fails. 

Example 

The following example creates a copy of the item square in the library folder test: 

f 1 . get Document DOM ( ). li bra ry.duplicatelt em ("test/square"); 

library.editltem() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary.editltemt [ namePath ] ) 
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Parameters 

name Path A string that specifies the name of the item. If the item is in a folder, you can specify 
its name and path using slash notation. If namePath is not specified, the single selected library 
item opens in Edit mode. If none or more than one item in the library is currently selected, the 
first scene in the main Timeline appears for editing. This parameter is optional. 

Returns 

A Boolean value: true if the specified item exists and can be edited; f al se otherwise. 
Description 

Method; opens the currently selected or specified item in Edit mode. 
Example 

The following example opens the item circle in the test folder of the library for editing: 

f 1 . get Document DOM ( ) . 1 i brary . edi tltem( "test/ci rcl e" ) ; 

library.expandFolder() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary .expandFolder( bExpand [, bRecurseNestedParents [, namePath ] ] ) 
Parameters 

bExpand A Boolean value: if true, the folder is expanded; if f al se (the default), the folder is 
collapsed. 

bRecurseNestedParents A Boolean value: if true, all the folders within the specified folder 
are expanded or collapsed, based on the value of bExpand. The default value is f al se. This 
parameter is optional. 

namePath A string that specifies the name and, optionally, the path of the folder to expand or 
collapse. If this parameter is not specified, the method applies to the currently selected folder. 
This parameter is optional. 

Returns 

A Boolean value: true if the item is successfully expanded or collapsed; f al se if unsuccessful or 
the specified item is not a folder. 

Description 

Method; expands or collapses the currently selected or specified folder in the library. 
Example 

The following example collapses the test folder in the library as well as all the folders within the 
test folder (if any) : 

f 1 . getDocumentDOM( ).li brary. expand Folder(false, true, "test"); 
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Iibrary.findltemlndex() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary.findltemlndex( namePath ) 
Parameters 

namePath A string that specifies the name of the item. If the item is in a folder, you can specify 
its name and path using slash notation. 

Returns 

An integer value representing the item's zero-based index value. 
Description 

Method; returns the library item's index value (zero-based). The library index is flat, so folders are 
considered part of the main index. Folder paths can be used to specify a nested item. 

Example 

The following example stores the zero-based index value of the library item square, which is in the 
test folder, in the variable sq I ndex, and then displays the index value in a dialog box: 

var sqlndex = f 1 . getDocumentDOM( ) . 1 i brary . f i ndltemlndex( "test/squa re" ) ; 
al ert(sqlndex) ; 

library.getltemPropertyO 

Availability 

Flash MX 2004. 
Usage 

1 ibrary.getItemProperty( property ) 
Parameters 

property A string. For a list of values that you can use as a property parameter, see the 
Property summary for the Item object, along with property summaries for its subclasses. 

Returns 

A string value for the property. 
Description 

Method; gets the property for the selected item. 
Example 

The following example shows a dialog box that contains the Linkage Identifier value for the 
symbol when referencing it using ActionScript or for runtime sharing: 

al ert ( f 1 . get Document DOM ( ) . 1 i brary . get ItemProperty ( "1 i nkageldenti f i er " ) ) ; 
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Mbrary.getltemTypeO 

Availability 

Flash MX 2004. 
Usage 

1 ibrary.getItemType( [ namePath ] ) 
Parameters 

namePath A string that specifies the name of the item. If the item is in a folder, specify its name 
and path using slash notation. If namePa th is not specified, Flash provides the type of the current 
selection. If more than one item is currently selected and no namePath is provided, Flash ignores 
the command. This parameter is optional. 

Returns 

A string value specifying the type of object. Possible values include: "undefined", "component", 
"movie clip", "graphic", "button", "video", "folder", "font", "sound", "bitmap", and 
"compiled clip". 

Description 

Method; gets the type of object currently selected or specified by a library path. 
Example 

The following example shows a dialog box that contains the item type of Symbol_l located in the 
Folder_l/Folder_2 folder: 

al ert ( f 1 . get Document DOM . 1 i brary . get I temfype( " Fol der_l/Fol der_2/Symbol_l " ) ) ; 

library.getSelectedltems() 

Availability 

Flash MX 2004. 
Parameters 

None. 
Returns 

An array of values for all currently selected items in the library. 
Description 

Method; gets the array of all currently selected items in the library. 
Example 

The following example stores the array of currently selected library items (in this case, several 
audio files) in the sel Items variable and then changes the sampl eRate property of the first 
audio file in the array to " 1 1 kHz": 
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var selltems = f 1 . getDocumentDOM( ) . 1 i brary . getSel ectedltems ( ) ; 
sel ltems[0] .sampleRate = "11 kHz"; 

library.importEmbeddedSWF() 

Availability 

Flash MX 2004. 
Usage 

1 i brary . importEmbeddedSWFt 1 inkageName, swfData [, libName^ ) 
Parameters 

1 i nkageName A string that provides the name of the SWF linkage of the root movie clip. 

swfData An array of binary SWF data, which comes from an external library or DLL. 

7 ibName A string that specifies the library name for the created item. If the name is already 
used, the method creates an alternate name. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; imports a Shockwave (SWF) file into the library as a compiled clip. Unlike File > 
Import > SWF, this method lets you embed a compiled SWF file inside the library. There is no 
corresponding UI functionality, and this method must be used with an external library or DLL 
(see Chapter 4, "C-Level Extensibility," on page 369). 

Example 

The following example adds the SWF file with the 7 i nkageName value of MyMovie to the library 
as a compiled clip named Intro: 

f 1 . getDocumentDOMt ) . 1 i brary . import Embedded SWF( "MyMovi e" , swfData , "Intro" ) ; 

library.itemExistsO 

Availability 

Flash MX 2004. 
Usage 

1 i bra ry . i temExi sts ( namePath ) 
Parameters 

namePath A string that specifies the name of the item. If the item is in a folder, specify its name 
and path using slash notation. 

Returns 

A Boolean value: true if the specified item exists in the library; fal se otherwise. 
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Description 

Method; checks to see if a specified item exists in the library. 
Example 

The following example displays trueorfalseina dialog box, depending on whether the item 
Symbol_l exists in the Folder_l library folder: 

al ert ( f 1 . ge t Document DOM ( ) . 1 i brary . i temExi sts ( ' Fol der_l/Symbol_l ' ) ) ; 

library.items 

Availability 

Flash MX 2004. 

Usage 

1 i bra ry . i terns 

Description 

Property; an array of item objects in the library. 
Example 

The following example stores the array of all library items in the i temArray variable: 
var itemArray = fl . getDocumentDOM( ). 1 i brary . i terns ; 

library.moveToFolder() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary.moveToFolder( folderPath [, iteinToMove [, bReplace ] ] ) 
Parameters 

folderPath Astring that specifies the path to the folder in the form "Fol derName" or 

" Fol der Name / Fol der Name". To move an item to the top level, specify an empty string ("") for 

folderPath. 

itemfoMo ve A string that specifies the name of the item to move. If itemfoMo ve is not 
specified, the currently selected items move. This parameter is optional. 

bRepl ace A Boolean value. If an item with the same name already exists, specifying true for 
the bReplace parameter replaces the existing item with the item being moved. If f al se, the 
name of the dropped item changes to a unique name. The default value is false. This parameter 
is optional. 

Returns 

A Boolean value: true if the item moves successfully; f al se otherwise. 
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Description 

Method; moves the currently selected or specified library item to a specified folder. If the 
fol derPath parameter is empty, the items move to the top level. 

Example 

The following example moves the item Symbol_l to the library folder new and replaces the item 
in that folder with the same name: 

f 1 . get Document DOM ( ) . 1 i brary .moveToFol der ( "new" , "Symbol_l " , true ) ; 

library.newFolder() 

Availability 

Flash MX 2004. 
Usage 

1 i bra ry . newFol der ( lfolderPath~\ ) 
Parameters 

fo 1 der Path A string that specifies the name of the folder to be created. If it is specified as a 
path, and the path doesn't exist, the path is created. This parameter is optional. 

Returns 

A Boolean value: true if folder is created successfully; f al se otherwise. 
Description 

Method; creates a new folder with the specified name, or a default name (" unti tl ed folder #") 
if no fol der Name parameter is provided, in the currently selected folder. 

Example 

The following example creates two new library folders; the second folder is a subfolder of the first 
folder: 

f 1 . get Document DOM ( ).library.newFolder("first/second"); 

Mbrary.renameltemO 

Availability 

Flash MX 2004. 
Usage 

1 i brary. renameltem( name) 
Parameters 

name A string that specifies a new name for the library item. 
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Returns 

A Boolean value: true if the name of the item changes successfully. If multiple items are selected, 
no names are changed, and the return value is false (to match UI behavior). 

Description 

Method; renames the currently selected library item in the Library panel. 
Example 

The following example renames the currently selected library item to new name: 
f 1 . ge t Document DOM ( ). 1 i bra ry . rename Item ( "new name" ) ; 

Nbrary.selectAIIO 

Availability 

Flash MX 2004. 
Usage 

1 i brary . sel ectAl 1 ( [ bSelectAll ] ) 
Parameters 

bSe 1 ectAl 1 A Boolean value that specifies whether to select or deselect all items in the library. 
Omit this parameter or use the default value of true to select all the items in the library; f al se 
deselects all library items. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; selects or deselects all items in the library. 
Example 

The following examples select all the items in the library: 

f 1 . get Document DOM ( ) . 1 i brary . sel ectAl 1 ( ) ; 

f 1 . ge t Document DOM ( ).library.selectAll(true); 

The following examples deselect all the items in the library: 

f 1 . getDocumentDOM( ) . 1 i brary . sel ectAl 1 (f al se) ; 
f 1 . get Document DOM ( ).library.selectNone(); 

library.selectltem() 

Availability 

Flash MX 2004. 
Usage 

1 i bra ry . sel ect Item( namePath [, bRepl aceCurrentSel ecti on [, bSelect ] ] ) 
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Parameters 

namePath A string that specifies the name of the item. If the item is in a folder, you can specify 
its name and path using slash notation. 

bRepl aceCurrentSel ecti on A Boolean value that specifies whether to replace the current 
selection or add the item to the current selection. The default value is true (replace current 
selection). This parameter is optional. 

bSe 1 ect A Boolean value that specifies whether to select or deselect an item. The default value 
is true (select). This parameter is optional. 

Returns 

A Boolean value: true if the specified item exists; f al se otherwise. 
Description 

Method; selects a specified library item. 
Example 

The following example changes the current selection in the library to symbol 1 inside 
untitled folder 1 : 

f 1 . get Document DOM ( ).library.selectltem("untitled Fol der_l/Symbol_l " ) ; 

The following example extends what is currently selected in the library to include symbol 1 inside 
untitled folder 1 : 

f 1 . ge t Document DOM ( ). li bra ry.selectlt em ("untitled Fol der_l/Symbol_l " , false); 

The following example deselects symbol 1 inside untitled folder 1 and does not change other 
selected items: 

f 1 . getDocumentDOM( ).library.selectltem("untitled Fol der_l/Symbol_l " , true , 
fal se) ; 

Nbrary.selectNoneO 

Availability 

Flash MX 2004. 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; deselects all the library items. 
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Example 

The following examples deselect all the items in the library: 

f 1 . ge t Document DOM ( ).library.selectNone(); 

f 1 . ge t Document DOM ( ) . 1 ibrary .sel ectAl 1 (f al se) ; 

library.setltemProperty() 

Availability 

Flash MX 2004. 
Usage 

1 ibrary .setltemPropertyt property, value ) 
Parameters 

property A string that is the name of the property to set. For a list of properties, see the 
Property summary for the Item object and property summaries for its subclasses. To see which 
objects are subclasses of the Item object, see Summary of the DOM structure. 

va 1 ue The value to assign to the specified property. 
Returns 

Nothing. 
Description 

Method; sets the property for all selected library items (ignoring folders). 
Example 

The following example assigns the value button to the symbol Type property for the selected 
library item or items. In this case, the item must be a Symbolltem object; symbol Type is a valid 
property for Symbolltem objects. 

Tl . get Document DOM ( ). li bra ry.setlt em Proper ty( "symbol Type" , "button ") ; 

library.updateltem() 

Availability 

Flash MX 2004. 
Usage 

1 i bra ry . updatel tem( [ namePath ] ) 
Parameters 

namePath A string that specifies the name of the item. If the item is in a folder, specify its name 
and path using slash notation. This is the same as right-clicking on an item and selecting Update 
from the menu in the UI. If no name is provided, the current selection is updated. This parameter 
is optional. 
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Returns 

A Boolean value: true if Flash updated the item successfully; f al se otherwise. 
Description 

Method; updates the specified item. 
Example 

The following example displays a dialog box that shows whether the currently selected item is 
updated (true) or not (f al se): 

al ert ( f 1 . get Document DOM ( J.library.updateltemO); 
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LinkedVideolnstance object 

Inheritance Element object > Instance object > LinkedVideolnstance object 
Availability 

Flash MX 2004. 
Description 

The LinkedVideolnstance object is a subclass of the Instance object. There are no unique 
methods or properties of LinkedVideolnstance. 
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Math object 

Availability 

Flash MX 2004. 
Description 

The Math object is available as a read-only property of the flash object; see f 1 . Math. This object 
provides methods that perform common mathematical operations. 

Method summary for the Math object 

The following methods are available for the Math object: 



Method 


Description 


Math . concatMatri x( ) 


Performs a matrix concatenation and returns the result. 


Math . i nvertMatri x( ) 


Returns the inverse of the specified matrix. 


Math . poi ntDi stancet ) 


Computes the distance between two points. 



Math.concatMatrix() 

Availability 

Flash MX 2004. 
Usage 

Math . concatMatri x( matl , matZ) 
Parameters 

matl and ma tZ Specify the Matrix objects to be concatenated (see Matrix object). Each 
parameter must be an object with fields a, b, c, d, tx, and ty. 

Returns 

A concatenated object matrix. 
Description 

Method; performs a matrix concatenation and returns the result. 
Example 

The following example stores the currently selected object in the el t variable, multiplies the 
object matrix by the view matrix, and stores that value in the mat variable: 

var elt = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 

var mat = fl .Math.concatMatrix( elt. matrix , f 1 . getDocumentD0M( ) . vi ewMatri x ); 
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Math.invertMatrix() 

Availability 

Flash MX 2004. 
Usage 

Math. invertMatrix( mat) 
Parameters 

mat Indicates the Matrix object to invert. It must have the following fields: a, b, c, d, tx, 
and ty. 

Returns 

A Matrix object that is the inverse of the original matrix. 
Description 

Method; returns the inverse of the specified matrix. 
Example 

The following example stores the currently selected object in the el t variable, assigns that matrix 
to the mat variable, and stores the inverse of the matrix in the i nv variable: 

var elt = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 

var mat = elt. matrix; 

var inv = f 1 . Math . i nvertMatri x( mat ); 

Math. point Distance() 
Availability 

Flash MX 2004. 
Usage 

Math . poi ntDi stance ( ptl , ptZ) 
Parameters 

ptl and pt2 Specify the points between which distance is measured. 
Returns 

A floating-point value that represents the distance between the points. 
Description 

Method; computes the distance between two points. 
Example 

The following example stores the value for the distance between ptl and ptZ in the di st 
variable: 

var ptl = |x:10, y:20) 
var pt2 = |x:100, y:200) 

var dist = fl . Math . poi ntDi stance( ptl , pt2); 
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Matrix object 

Availability 

Flash MX 2004. 
Description 

The Matrix object represents a transformation matrix. 

Property summary for the Matrix object 

The following properties are available for the Matrix object: 



Property Description 



matrix 


, a 


Property; a floating-point value that specifies the (0,0) element in the 
transformation matrix. 


matri x 


,b 


Property; a floating-point value that specifies the (0,1) element in the matrix. 


matri x 


, c 


Property; a floating-point value that specifies the (1,0) element in the matrix. 


matrix 


,d 


Property; a floating-point value that specifies the (1,1) element in the matrix. 


matri x 


,tx 


Property; a floating-point value that specifies the x-axis location of a symbol's 
registration point or the center of a shape. 


matri x 


• ty 


Property; a floating-point value that specifies the y-axis location of a symbol's 
registration point or the center of a shape. 



matrix.a 

Availability 

Flash MX 2004. 

Usage 

matri x . a 

Description 

Property; a floating-point value that specifies the (0,0) element in the transformation matrix. This 
value represents the scale factor of the object's x-axis. 

Example 

The a and d properties in a matrix represent scaling. In the following example, the values are set 
to 2 and 3, respectively, to scale the selected object to two times its width and three times its 
height: 

var mat = fl . getDocumentDOM( ). sel ecti on [0] .matri x ; 
mat . a = 2 ; 
mat . d = 3 ; 

fl . getDocumentDOMt ). sel ecti on[0] .matri x = mat; 
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You can rotate an object by setting the a, b, c, and d matrix properties relative to one another, 
where a = d and b = - c. For example, values of 0.5, 0.8, -0.8, and 0.5 rotate the object 60°: 

var mat = f 1 . getDocumentD0M( ) . sel ecti on [0] .matri x ; 
mat . a = 0.5; 
mat.b = 0.8; 
mat.c = 0.8*( -1) ; 
mat . d = 0.5; 

fl . getDocumentD0M( ). sel ecti on[0] .matri x = mat; 

You can set a = d = 1 and c = b = 0 to reset the object back to its original shape. 

matrix.b 

Availability 

Flash MX 2004. 

Usage 

matrix.b 

Description 

Property; a floating-point value that specifies the (0,1) element in the matrix. This value 
represents the vertical skew of a shape; it causes Flash to move the shape's right edge along the 
vertical axis. 

The matrix.b and ma t r i x . c properties in a matrix represent skewing. 
Example 

In the following example, you can set b and c to -1 and 0, respectively; these settings skew the 
object at a 45° vertical angle: 

var mat = fl . getDocumentD0M( ). sel ecti on [0] .matri x ; 
mat . b = - 1 ; 
mat . c = 0 ; 

fl . getDocumentDOMt ). sel ecti on[0] .matri x = mat; 

To skew the object back to its original shape, you can set b and c to 0. 

See the m a t r i x . a example. 

matrix.c 

Availability 

Flash MX 2004. 

Usage 

matrix.c 

Description 

Property; a floating-point value that specifies the (1,0) element in the matrix. This value causes 
Flash to skew the object by moving its bottom edge along a horizontal axis. 

The matrix.b and matrix.c properties in a matrix represent skewing. 
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Example 

See the m a t r i x . b example. 

matrix.d 

Availability 

Flash MX 2004. 

Usage 

matrix.d 

Description 

Property; a floating-point value that specifies the (1,1) element in the matrix. This value 
represents the scale factor of the object's y- axis. 

Example 

See matri x . a. 

matrix.tx 

Availability 

Flash MX 2004. 

Usage 

matri x . tx 

Description 

Property; a floating-point value that specifies the x-axis location of a symbol's registration point or 
the center of a shape. It defines the x translation of the transformation. 

You can move an object by setting the matri x . tx and matri x . ty properties. 

Example 

In the following example, setting tx and ty to 0 moves the registration point of the object to 
point 0,0 in the document: 

var mat = fl . getDocumentD0M( ). sel ecti on [0] .matri x ; 
mat . tx = 0 ; 
mat . ty = 0 ; 

fl . getDocumentDOMt ). sel ecti on[0] .matri x = mat; 

matrix.ty 

Availability 

Flash MX 2004. 

Usage 

matri x . ty 
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Description 

Property; a floating-point value that specifies the y-axis location of a symbol's registration point or 
the center of a shape. It defines the y translation of the transformation. 

You can move an object by setting the matri x . tx and matri x . ty properties. 

Example 

See the m a t r i x . t x example. 
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outputPanel object 



Availability 

Flash MX 2004. 
Description 

This object represents the Output panel, which displays troubleshooting information such as 
syntax errors. To access this object, use f 1 . outputPanel (or flash. outputPanel). 

Method summary for the outputPanel object 

The outputPanel object uses the following methods. 



Method 




Description 


outputPanel 


. cl ea r ( ) 


Method; clears the contents of the Output panel. 


outputPanel 


. save( ) 


Method; saves the contents of the Output panel to a local text file, in UTF-8 






encoding. 


outputPanel 


.trace( ) 


Method; adds a line to the contents of the Output panel, terminated by a 






new line. 



outputPanel. clear() 

Availability 

Flash MX 2004. 

Usage 

outputPanel . cl ear ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; clears the contents of the Output panel. You can use this method in a batch processing 
application to clear a list of errors, or to save them incrementally by using this method with 

outputPanel .save( ). 

Example 

The following example clears the current contents of the Output panel: 

fl .outputPanel . cl ear ( ) ; 
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outputPanel.save() 

Availability 

Flash MX 2004. 
Usage 

outputPanel . save( f i leURI [, bAppendToFi 1 e] ) 
Parameters 

f / leURI A string that specifies the local file to contain the Output panel's contents. 

bAppendToFi le optional parameter, if it has a value of true, appends the Output panel's 
contents to the output file. If bAppendToFi 7 e is false, the method overwrites the output file if it 
already exists. The default value is false. 

Returns 

Nothing. 
Description 

Method; saves the contents of the Output panel to a local text file, in UTF-8 encoding. The local 
filename must be specified as a URL You can also specify that the contents be appended to the 
contents of a local file, rather than being overwritten. If the URI is invalid or unspecified, an error 
is reported. 

This method is useful for batch processing. For example, you can create a JSFL file that compiles 
several components. Any compile errors appear in the Output panel, and you can use this method 
to save the resulting errors to a text file, which can be automatically parsed by the build system in 
use. 

Example 

The following example saves the Output panel's contents to the batch.log file in the /tests folder: 
fl .outputPanel . save( "fi 1 e : ///c | /tests/batch . 1 og" ) ; 

outputPanel.trace() 

Availability 

Flash MX 2004. 
Usage 

outputPanel . trace ( message) 
Parameters 

The message parameter is a string that contains the text to add to the Output panel. 
Returns 
Nothing. 
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Description 

Method; adds a line to the contents of the Output panel, terminated by a new line. This method 
shows the Output panel if it is not already visible. 

The outputPanel . trace( ) method duplicates the functionality of f 1 . trace( ). 
Example 

The following example writes "hello wo r 1 d " to the Output panel: 

fl .outputPanel . trace ( " hello world"); 
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Parameter object 

Availability 

Flash MX 2004. 
Description 

The Parameter object type is accessed from the screen, pa rameters array (which corresponds to 
the screen Property inspector in the Flash authoring tool) or by the 
componentlnstance. parameters array (which corresponds to the component Property 
inspector in the authoring tool). 

Method summary for the Parameter object 

The following methods are available for the Parameter object: 
Method Description 

parameter . i nsertltem( ) Method; if a parameter is a list, object, or array, the value property is an 
array. 

parameter . removeltemf ) Method; removes an element of the list, object, or array type of a screen or 
component parameter. 

Property summary for the Parameter object 

The following properties are available for the Parameter object: 
Property Description 



parameter 


category 


Property; string that specifies the category property for the screen 
parameter or componentlnstance parameter. 


parameter 


1 i stlndex 


Property; an integer that specifies the value of the selected list item. 


parameter 


name 


Read-only; a string that specifies the name of the parameter. 


parameter 


val ue 


Property; corresponds to the Value field in the Parameters tab of the 
Component Inspector panel, in the component Property inspector, or in 
the screen Property inspector. 


parameter 


val ueType 


Read-only; a string that indicates the type of the screen or component 
parameter. 


parameter 


verbose 


Read-only; specifies whether the parameter appears in the Parameters 
tab of the Component inspector panel, the Parameters tab of the Property 
inspector, or the Components Inspector panel. 



parameter.category 

Availability 

Flash MX 2004. 

Usage 

parameter . category 
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Description 

Property; a string that specifies the category property for the screen parameter or 
componentlnstance parameter. This property provides an alternative way of presenting a list of 
parameters. This functionality is not available through the Flash user interface. 

parameter.insertltem() 

Availability 

Flash MX 2004. 
Usage 

pa rameter . i nsert I tem( index, name, value, type) 
Parameters 

index A zero-based integer index that indicates where the item will be inserted in the list, 
object, or array. If the index is 0, the item is inserted at the beginning of the list. If index value is 
greater than the list size, the new item is inserted at the end of the array. 

name A string that specifies the name of the item to insert. This is a required parameter for 
object parameters. 

va 1 ue A string that specifies the value of the item to insert. 

type A string that specifies the type of item to insert. 
Returns 

Nothing. 
Description 

Method; if a parameter is a list, object, or array, the value property is an array. Use this method to 
insert a value into the array. 

Example 

The following example inserts the value of " New Value" into the 1 abel PI acement parameter: 

// select an instance of a Button component on the Stage 
var parms = fl . getDocumentDOM( ). sel ecti on [0] . parameters ; 
pa rms [2] . i nsert I tem( 0 , "name", "New Value", "String"); 
var values = parms [2] . val ue ; 
for (var prop in values)! 

fl . trace (" 1 abel PI acement parameter value = " + val ues[prop] . val ue) ; 

( 

parameter.listlndex 

Availability 

Flash MX 2004. 

Usage 

pa rameter . 1 i st Index 
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Description 

Property; the value of the selected list item. This property is valid only if the val ueType 
parameter is "List". 

Example 

The following example sets the first parameter for a Slide, which is the autoKeyNav parameter. To 
set the parameter to one of its acceptable values (true, f al se, or i nheri t) 
pa ra meter . 1 i st Index is set to the index of the item in the list (0 for true, 1 for f al se, 2 for 
i nheri t). 

var parms = fl . getDocumentDOMt ). screenOutl i ne . screens [ 1] . parameters ; 
pa rms [0] . 1 i st Index = 1 ; 

parameter.name 

Availability 

Flash MX 2004. 

Usage 

pa rameter . name 

Description 

Read-only property; a string that specifies the name of the parameter. 
Example 

The following example shows the name of the fifth parameter for the selected component: 

var parms = fl . getDocumentDOMt ). sel ecti on [0] . parameters ; 
fl . tracet "name : " + pa rms [4] . name ) ; 

The following example shows the name of the fifth parameter for the specified screen: 

var parms = fl . getDocumentDOMt ). screenOutl i ne . screens [ 1] . pa rameters ; 
fl . tracet "name : " + parms[4] .name) ; 

parameter.removeltem() 

Availability 

Flash MX 2004. 
Usage 

parameter. removeltemt index) 
Parameters 

index The zero-based integer index of the item to remove from the screen or component 
property. 

Returns 

Nothing. 
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Description 

Method; removes an element of the list, object, or array type of a screen or component parameter. 
Example 

The following example removes the element at index 1 from the label PI acement parameter of a 
component: 

// select an instance of a Button component on the Stage 
var parms = fl . getDocumentDOM( ). sel ecti on [0] . parameters ; 
var values = parms [2] . val ue ; 
fl. trace ("--Original--"); 
fortvar prop in values)! 

f 1 . trace (" 1 abel PI acement value = " + val ues[prop] .val ue) ; 

( 

pa rms [2] . remove I tem( 1 ) ; 

var newValues = parms [2] . val ue ; 

f 1 . trace( "- -After Removing Item--"); 

fortvar prop in newValuesH 

f 1 . trace (" 1 abel PI acement value = " + newVal ues[prop] .val ue) ; 

( 

The following example removes the element at index 1 from the autoKeyNav parameter of a 
screen: 

// open a presentation document 

var parms = fl . getDocumentDOM( ). screenOutl i ne . screens [ 1] . pa rameters ; 
var values = parms [0] . val ue ; 
f 1 . trace( " - -Ori gi nal - - " ) ; 
for(var prop in values)! 

fl .trace( "autoKeyNav value = " + val ues[prop] .val ue) ; 

( 

pa rms [0] . remove I tem( 1 ) ; 

var newValues = parms [0] . val ue ; 

f 1 . trace( "- -After Removing Item--"); 

for(var prop in newValues)! 

fl . trace ( "autoKeyNav value = " + newVal ues[prop] .val ue) ; 

( 

parameter.value 

Availability 

Flash MX 2004. 

Usage 

pa rameter . val ue 
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Description 

Property; corresponds to the Value field in the Parameters tab of the Component Inspector panel, 
in the component Property inspector, or in the screen Property inspector. The type of the value 
property is determined by the val ueType property for the parameter (see 
parameter.val ueType). 

parameter.valueType 

Availability 

Flash MX 2004. 

Usage 

parameter. val ueType 

Description 

Read-only property; a string that indicates the type of the screen or component parameter. The 
type can be one of the following values: "Default", "Array", "Object", "List", "String", 
"Number", "Bool ean", "Font Name", "Col or", "Col 1 ecti on", "Web Service URL", or "Web 
Service Operation". 

parameter.verbose 
Availability 

Flash MX 2004. 

Usage 

pa rameter . verbose 

Description 

Read-only property; specifies whether the parameter appears in the Parameters tab of the 
Component inspector panel, the Parameters tab of the Property inspector, or the Components 
Inspector panel. This property contains a value of 0 (nonverbose) or 1 (verbose). 



Parameter object 241 



Path object 

Availability 

Flash MX 2004. 
Description 

The Path object defines a sequence of line segments (straight, curved, or both), which you 
typically use when creating extensible tools. The following example shows an instance of a Path 
object being returned from the flash object: 

path = fl .drawingLayer.newPatht ) ; 
See also the drawingLayer object. 

Method summary for the Path object 

The following methods are available for the Path object: 



Method Description 



path 


. addCubi cCurvet ) 


Method; appends a cubic Bezier curve segment to the path. 


path 


.addCurvet ) 


Method; appends a quadratic Bezier segment to the path. 


path 


.addPointt ) 


Method; adds a point to the path. 


path 


. cl ear ( ) 


Method; removes all points from the path. 


path 


. cl ose( ) 


Method; appends a point at the location of the first point of the path 
and extends the path to that point, which closes the path. 


path 


,makeShape( ) 


Method; creates a shape on the Stage by using the current stroke 
and fill settings. 


path 


. newContour( ) 


Method; starts a new contour in the path. 



Property summary for the Path object 

The following properties are available for the Path object: 
Property Description 

path .nPts Read-only; an integer representing the number of points in the path. 

path.addCubicCurve() 

Availability 

Flash MX 2004. 

Usage 

path . addCubi cCurve ( xAnchor , yAnchor, xZ, yZ, x3, y3, x4, y4) 
Parameters 

x Anchor A floating-point number that specifies the x position of the first control point. 
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y Anchor A floating-point number that specifies the y position of the first control point. 

xZ A floating-point number that specifies the x position of the second control point. 

yZ A floating-point number that specifies the y position of the second control point. 

x3 A floating-point number that specifies the x position of the third control point. 

y3 A floating-point number that specifies the y position of the third control point. 

x4 A floating-point number that specifies the x position of the fourth control point. 

y4 A floating-point number that specifies the y position of the fourth control point. 
Returns 

Nothing. 
Description 

Method; appends a cubic Bezier curve segment to the path. 
Example 

The following example creates a new path, stores it in the my Path variable, and assigns the curve 
to the path: 

var myPath = fl .drawingLayer.newPath( ) ; 
myPath.addCubicCurve(0, 0, 10, 20, 20, 20, 30, 0); 

path.addCurve() 

Availability 

Flash MX 2004. 
Usage 

path . addCurve ( xAnchor, yAnchor, xZ, yZ, x3, y3) 
Parameters 

x Anchor A floating-point value that specifies the x position of the first control point. 

yAnchor A floating-point value that specifies the y position of the first control point. 

xZ A floating-point value that specifies the x position of the second control point. 

yZ A floating-point value that specifies the y position of the second control point. 

x3 A floating-point value that specifies the x position of the third control point. 

y3 A floating-point value that specifies the y position of the third control point. 
Returns 

Nothing. 
Description 

Method; appends a quadratic Bezier segment to the path. 
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Example 

The following example creates a new path, stores it in the my Path variable, and assigns the curve 
to the path: 

var myPath = fl .drawingLayer.newPath( ) ; 
myPath.addCurve(0, 0, 10, 20, 20, 0); 

path.addPoint() 

Availability 

Flash MX 2004. 

Usage 

path . addPoi nt ( x, y) 

Parameters 

x A floating-point value that specifies the x position of the point. 

y A floating-point value that specifies the y position of the point. 
Returns 

Nothing. 
Description 

Method; adds a point to the path. 
Example 

The following example creates a new path, stores it in the my Path variable, and assigns the new 
point to the path: 

var myPath = fl .drawingLayer.newPath( ) ; 
myPath. addPointdO, 100); 

path.clear() 

Availability 

Flash MX 2004. 

Usage 

path . cl ea r ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; removes all points from the path. 
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Example 

The following example removes all points from a path stored in the my Path variable: 

var myPath = fl .drawingLayer.newPath( ) ; 
myPath . cl ear ( ) ; 

path.close() 

Availability 

Flash MX 2004. 

Usage 

path . cl ose( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; appends a point at the location of the first point of the path and extends the path to that 
point, which closes the path. If the path has no points, no points are added. 

Example 

The following example creates a closed path: 

var myPath = fl .drawingLayer.newPath( ) ; 
myPath . cl ose ( ) ; 

path.makeShape() 

Availability 

Flash MX 2004. 
Usage 

path . ma keShape ( IbSupressFi 1 1 [, bSupressStrokeH) 
Parameters 

bSuppressFi 1 1 A Boolean value that, if set to true, suppresses the fill that would be applied to 
the shape. The default value is f al se. This parameter is optional. 

bSupressStroke A Boolean value that, if set to true, suppresses the stroke that would be 
applied to the shape. The default value is f al se. This parameter is optional. 

Returns 

Nothing. 
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Description 

Method; creates a shape on the Stage by using the current stroke and fill settings. The path is 
cleared after the shape is created. This method has two optional parameters for suppressing the fill 
and stroke of the resulting shape object. If you omit these parameters or set them to f al se, the 
current values for fill and stroke are used. 

Example 

The following example creates a shape with the current fill and no stroke: 

var myPath = fl .drawingLayer.newPath( ) ; 
my Path . makeShape ( f al se , true); 

path.newContour() 

Availability 

Flash MX 2004. 

Usage 

path . newContour ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; starts a new contour in the path. 
Example 

The following example creates a hollow square: 

var myPath = fl .drawingLayer.newPath( ) ; 

myPath. addPoinU 0, 0); 

myPath. addPoinU 0, 30); 

myPath. addPoi nt (30 , 30); 

myPath. addPointdO, 0); 

myPath. addPoinU 0, 0); 

myPath.newContour( ) ; 
myPath. addPointdO, 10); 
myPath. addPointdO, 20); 
myPath. addPoint(20, 20); 
myPath. addPoint(20, 10); 
myPath. addPointdO, 10); 

myPath. makeShape( ) ; 
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path.nPts 

Availability 

Flash MX 2004. 

Usage 

path . nPts 

Description 

Read-only property; an integer representing the number of points in the path. A new path 
has 0 points. 

Example 

The following example uses the Output panel to show the number of points in the path 
referenced by the my P a t h variable: 

var myPath = fl .drawingLayer.newPath( ) ; 
var numOf Poi nts = myPath.nPts; 

fl . trace( "Number of points in the path: " + numOf Poi nts ) ; 
// displays: Number of points in the path: 0 
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Screen object 

Availability 

Flash MX 2004. 
Description 

The Screen object represents a single screen in a slide or form document. This object contains 
properties related to the slide or form. For access to the array of all Screen objects in the 
document, use the following code: 

f 1 . getDocumentDOMt ).screenOutline. screens 

Property summary for the Screen object 

The Screen object has the following properties: 



Properties Description 



screen 


. accName 


Property; a string that is equivalent to the Name field in the Accessibility 
panel. 


screen 


. chi 1 dScreens 


Read-only; the array of child screens for this screen. The array is empty if 
there are no child screens. 


screen 


. descri pti on 


Property; a string that is equivalent to the Description field in the 
Accessibility panel. 


screen 


. forceSimpl e 


Property; a Boolean value that enables and disables accessibility for the 
object's children. 


screen 


. hidden 


Property; a Boolean value that specifies whether a screen is visible. 


screen 


. i nstanceName 


Read-only; a string that represents the instance name used to access the 
object from ActionScript. 


screen 


.name 


Read-only; a string that represents the name of the screen. 


screen 


nextScreen 


Read-only; an object that represents the next peer screen in the parent's 

chi 1 dScreen array. 


screen 


.parameters 


Read-only; an array of ActionScript properties that are accessible from 
the screen Property inspector. 


screen 


.parentScreen 


Read-only; an object that represents the parent screen. 


screen 


. prevScreen 


Read-only; an object that represents the previous peer screen in the 
parent's chi 1 dScreen array. 


screen 


. si 1 ent 


Property; a Boolean value that specifies whether the object is accessible. 


screen 


.tablndex 


Property; equivalent to the Tab Index field in the Accessibility panel. 


screen 


. ti mel i ne 


Read-only; the Timeline object for the screen. 
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screen.accName 

Availability 

Flash MX 2004. 

Usage 

screen . accName 

Description 

Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers 
identify objects by reading the name aloud. 

Example 

The following example stores the value of the name of the object in the theName variable: 
var theName = fl . getDocumentDOM( ). screenOutl i ne . screens [ 1] . accName ; 
The following example sets the name of the object to "Home Button": 
fl . getDocumentDOM( ) .screenOutl ine.screens[l] .accName = 'Home Button'; 

screen.childScreens 

Availability 

Flash MX 2004. 

Usage 

screen . chi 1 dScreens 

Description 

Read-only property; the array of child screens for this screen. The array is empty if there are no 
child screens. 

Example 

The following example checks to see if the current document is a slide or form, and if it is, stores 
the array of child screens in the myChi 1 dren variable and displays their names in the Output 
panel: 

var myChildren = new ArrayU; 

i f ( f 1 . get Document DOM ( J.allowScreens) { 

var myParent = fl . getDocumentDOM( ). screenOutl i ne . rootScreen . name 
for (i in fl . getDocumentDOM( ). screenOutl i ne . rootScreen . chi 1 dScreens ) { 
myChi 1 dren . push ( " 

"+f 1 . get Document DOM ( ). screenOutl ine. rootScreen. childScreens[i]. name); 
I 

fl.traceC fhe child screens of "+myParent+" are "+myChi 1 dren+" . "); 

I 
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screen. description 

Availability 

Flash MX 2004. 

Usage 

screen . descri pti on 

Description 

Property; a string that is equivalent to the Description field in the Accessibility panel. The 
description is read by the screen reader. 

Example 

The following example gets the description of the object and stores it in the theDescri pti on 
variable: 

var theDescri pti on = fl . getDocumentDOM( ). screenOutl i ne . screens [1 ]. descri pti on ; 

The following example sets the description of the object to "Thi s is Screen 1": 

fl . getDocumentDOM( ). screenOutl i ne . screens [ 1] . descri pti on = "This is Screen 1" 

screen.forceSimple 

Availability 

Flash MX 2004. 

Usage 

screen . f orceSimpl e 

Description 

Property; a Boolean value that enables or disables accessibility for the object's children. This is 
equivalent to the inverse logic of the Make Child Objects Accessible setting in the Accessibility 
panel. That is, if f orceSi mpl e is t rue, it is the same as the Make Child Object Accessible option 
being deselected. If force Si mpl e is false, it is the same as the Make Child Object Accessible 
option being selected. 

Example 

The following example stores the value of f orceSi mpl e in the areChildrenAccessible 
variable (a value of f a 1 se means the children of the object are accessible): 

var areChildrenAccessible = 

fl . get Document DOM ( ). screenOutl ine.screens[l].forceSimple 

The following example makes the children of the object accessible: 

f 1 . getDocumentDOM( ). screenOutl i ne. screens [1] . f orceSimpl e = false; 
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screen. hidden 

Availability 

Flash MX 2004. 

Usage 

screen . hi dden 

Description 

Property; a Boolean value that specifies whether the screen is visible. A screen with the hidden 
property set to true is not visible in any other screen. 

Example 

The following example checks to see if the first screen in the outline is hidden and changes the 
visibility of the screen accordingly. Then, a message in the Output panel shows what the visibility 
of the screen was before the change: 

if ( fl . getDocumentDOMt ). screenOutl i ne . screens [0] . hi dden ) { 

fl .getDocumentDOMt ). screenOutl ine.setScreenPropertyt" hidden", false); 
fl .tracetfl . get Document DOM ( ).screenOutline.screens[0] . natne+" had its 
'hidden' property set to 'false'"); 

I 

else ( 

fl .getDocumentDOMt ). screenOutl ine.setScreenProperty(" hidden", true); 
fl .tracetfl . getDocumentDOMt ) .screenOutl ine.screens[0] . name+" had its 
'hidden' property set to 'true'"); 



screen. instanceName 

Availability 

Flash MX 2004. 

Usage 

screen . i nstanceName 

Description 

Read-only property; a string that represents the instance name used to access the object from 
ActionScript. 

Example 

The following example checks to see if the current document allows screens (because it is a slide 
or form). Then, it assigns the i nstanceName value of the first child screen in the array to the 
my InstanceName variable and opens the Output panel to show the instance name of the screen: 

var myChildren = new Arrayt); 
i f ( f 1 . getDocumentDOMt KallowScreens) { 
var my InstanceName = 

f 1 . getDocumentDOMt ). screenOutl ine.rootScreen.childScreens[0].i nstanceName; 
fl.tracet" fhe instanceName is "+my InstanceName+" . "); 

I 
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screen. name 

Availability 

Flash MX 2004. 

Usage 

screen . name 

Description 

Read-only property; a string that represents the name of the screen. 
Example 

The following example checks to see if the current document allows screens (because it is a slide 
or form document). Then, it assigns the name value of the first child screen in the array to the 
my Name variable and opens the Output panel to show the name of the screen: 

var myChildren = new ArrayU; 
i f ( f 1 . get Document DOM ( KallowScreens) { 
var myName = 

f 1 . ge t Document DOM ( ).screenOutline.rootScreen.childScreens[0].name; 
fl . tracet "The name of the screen is "+myName+" . "); 

} 

screen. nextScreen 

Availability 

Flash MX 2004. 

Usage 

screen . nextScreen 

Description 

Read-only property; an object that represents the next peer screen in the parent's childScreen 
array. That is, screen. NextScreen is found by moving down an array of child screens to the next 
screen in the array. See screen . prevScreen. 

If there isn't a peer screen, the value is null. 

Example 

The following example first checks to see if the current document is a slide or form, and if it is, 
retrieves and shows the sequence of screens in the Output panel: 

i f ( f 1 . ge t Document DOM ( ) . al 1 owScreens ) { 
var myCurrent = 

f 1 . ge t Document DOM ( ).screenOutline.rootScreen.childScreens[0].name; 
var myNext = 

f 1 . ge t Document DOM ( ).screenOutline.rootScreen.childScreens[0]. next Screen. nam 
e ; 

f 1 . tracet" The next screen to "+myCurrent+" is "+myNext+". "); 

I 
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screen. parameters 

Availability 

Flash MX 2004. 

Usage 

screen . pa rameters 

Description 

Read-only property; an array of ActionScript properties that are accessible from the screen 
Property inspector. 

Example 

The following example stores the parameters for the second screen in the outline to the pa rms 
variable and then assigns the "some val lie" value to the first property: 

var parms = fl . getDocumentDOM( ). screenOutl i ne . screens [ 1] . pa rameters ; 
pa rms [0] . val ue = "some value"; 

screen. parentScreen 
Availability 

Flash MX 2004. 

Usage 

screen . pa rentScreen 

Description 

Read-only property; an object that represents the parent screen. If parentScreen is null, the 
screen is a top-level screen. 

Example 

The following example stores the values for the childScreens and parentScreen properties in 
variables and then shows those values and their parent/child relationship in the Output panel: 

i f ( f 1 . get Document DOM ( J.allowScreens) { 
var myCurrent = 

f 1 . ge t Document DOM ( ). screenOutl ine.rootScreen.childScreens[l]. name; 
var myParent = 

f 1 . ge t Document DOM ( ) . screenOutl ine.rootScreen.childScreens[l]. parentScreen. n 
ame ; 

fl.tracet" The parent screen to "+myCurrent+" is "+myParent+" . "); 

} 
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screen. prevScreen 

Availability 

Flash MX 2004. 



Usage 

screen . prevScreen 

Description 

Read-only property; an object that represents the previous peer screen in the parent's 

chi 1 dScreens array. If there isn't a peer screen, the value is nul 1 . See also screen . nextScreen. 

Example 

The following example checks to see if the current document is a slide or form, and if it is, 
retrieves and shows the sequence of screens in the Output panel: 

i f ( f 1 . ge t Document DOM ( ) . al 1 owScreens ) { 
var myCurrent = 

f 1 . ge t Document DOM ( ).screenOutline.rootScreen.childScreens[l].name; 
var myNext = 

f 1 . ge t Document DOM ( ).screenOutline.rootScreen.childScreens[l]. prevScreen. nam 
e ; 

fl.tracet" The previous screen to "+myCurrent+" is "+myNext+". "); 

1 

screen.silent 

Availability 

Flash MX 2004. 

Usage 

screen . si 1 ent 

Description 

Property; a Boolean value that specifies whether the object is accessible. This is equivalent to the 
inverse logic of the Make Object Accessible setting in the Accessibility panel. That is, if s i 1 ent is 
true, it is the same as having the Make Object Accessible option deselected in the Accessibility 
panel. If si 1 ent is f al se, it is the same as having the Make Object Accessible option selected in 
the Accessibility panel. 

Example 

The following example retrieves the silent value of the object (a value of f a 1 s e means the object 
is accessible): 

var isSilent = fl . getDocumentDOM( ). screenOutl i ne . screens [1 ]. si 1 ent ; 

The following example sets the object to be accessible: 

fl . getDocumentDOM( ). screenOutl i ne . screens [ 1] . si 1 ent = false; 



254 Chapter 3: Objects 



screen.tablndex 

Availability 

Flash MX 2004. 

Usage 

screen . tablndex 

Description 

Property; equivalent to the Tab Index field in the Accessibility panel. This value lets you 
determine the order in which objects are accessed when the user presses the Tab key. 

Example 

The following example gets the tab index of the object: 

var theTablndex = fl . getDocumentDOM( ). screenOutl i ne . screens [1 ]. tablndex ; 

The following example sets the tab index of the object to 1: 

fl .getDocumentDOMt ) .screenOutl ine.screens[l] .tablndex = 1; 

screen.timeline 

Availability 

Flash MX 2004. 

Usage 

screen .time! i ne 

Description 

Read-only property; the Timeline object for the screen. 
Example 

The following example gets the screenOutl ine property of the current slide document, assigns 
the array of t i mel i ne properties for the first screen to myArray, and displays those properties in 
the Output panel: 

myArray = new ArrayU; 

i f ( f 1 . getDocumentDOMt ). screenOutl ine) { 

ford' in fl . getDocumentDOMt ). screenOutl i ne . screens [0] . ti mel i ne ) { 

myArray. pusht " "+i+" : 

"+f 1 . getDocumentDOMt ). screenOutl ine.screens[0].ti me 1 i ne[ i ] + " ") ; 
I 

f 1 . tracet "Here are the properties of the screen named "+ 

f 1 . getDocumentDOMt ) . screenOutl ine.screens[0] . name+" : "+myArray ) ; 

I 
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ScreenOutline object 



Availability 

Flash MX 2004. 
Description 

The ScreenOutline object represents the group of screens in a slide or form document. The object 
is accessed by using f 1 . getDocumentDOM( ) . screenOutl i ne . 

The ScreenOutline object exists only if the document is a slide or form document, so before 
accessing the property, use document .all owScreens ( ) to verify that a Screens document exists, 
as shown in the following example: 

i f ( f 1 . ge t Document DOM ( ) . al 1 owScreens ) { 

var myName = 

f 1 . ge t Document DOM ( ). screenOutl ine.rootScreen.childScreens[0]. name; 
f 1 . tracet "The name of the screen is " + myName + ". "); 

} 

Method summary for the ScreenOutline object 

You can use the following methods with the ScreenOutline object: 



Method Description 

screenOutl i ne . copyScreenFromFi let) Method; inserts all the screens, or a named screen and its 

children, from a specified document under the currently 
selected screen. 

screenOutl i ne.del eteScreent ) Method; deletes the currently selected screen(s), or a 

specified screen, and the children of the screen(s). 

screenOutl i ne.dupl icateScreent ) Method; duplicates the currently selected screen(s) or a 

specified screen. 

screenOutl i ne . getSel ectedScreens ( ) Method; returns an array of Screen objects that are 

currently selected in the screen outline. 

screenOutl i ne . i nsertNestedScreen ( ) Method; inserts a nested screen of a specific type into a 

particular location in the screen outline. 

screenOutl i ne . i nsertScreen ( ) Method; inserts a new blank screen of a specified type 

into the document at a specified location. 

screenOutl i ne . moveScreen ( ) Method; moves the specified screen in relation to the 

value of the referenceScreen parameter; either before, 
after, as the first child, or as the last child. 

screenOutl i ne . renameScreen ( ) Method; changes the screen with a specified name to a 

new name. 

screenOutl i ne . set Cur rent Screen ( ) Method; lets the current selection in the screen outline to 

the specified screen. 
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Method 



Description 



screenOutl i ne . set Screen Property ( ) Method; lets the specified property with the specified 

value for the selected screens. 

screenOutl i ne . setSel ectedScreens ( ) Method; selects the specified screens in the Screen 

Outline pane. 



Property summary for the ScreenOutline object 

You can use the following properties with the ScreenOutline object: 



Property 




Description 


screenOutl i ne 


currentScreen 


Property; a Screen object; the currently selected screen. 


screenOutl i ne 


rootScreen 


Read-only; the first screen in the screen outline. 


screenOutl i ne 


screens 


Read-only ; the array of top level Screen objects 
contained in the document (see Screen object). 



screenOutline.copyScreenFromFileO 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . copyScreenFromFi 1 e( fileURI [, screenName^ ) 
Parameters 

f 7 1 eURI Astring that specifies a filename for the authoring file that contains the screens to 
copy into the document, in URI format (for example, "file:///C:/assets.fla"). 

screenname The name of the screen to copy. If the screenName parameter is present, Flash 
copies that screen and its children. If the screenName is not specified, Flash copies the whole 
document. This parameter is optional. 

Returns 

Nothing. If the file is not found or is not a valid FLA file, or if the specified screen is not found, 
an error is reported and the script is cancelled. 

Description 

Method; inserts all the screens, or a named screen and its children, from a specified document 
under the currently selected screen. If more than one screen is selected, the screen(s) are inserted 
under the last selected screen, as its sibling. 

Example 

The following example copies the "slidel" screen from the myTarget.fla file on the Desktop into 
the current document (substitute your user name for userName): 

f 1 . getDocumentDOM( ). screenOutl ine.copyScreenFromFile("file:///C| /Documents and 
Setti ngs/ user/Vame/Desktop/myTarget . f 1 a " , "slidel"); 
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screenOutline.currentScreen 

Availability 

Flash MX 2004. 
Usage 

screenOutline.currentScreen 
Description 

Property; a Screen object, the currently selected screen. 
Example 

The following example stores the currentScreen object in the my Screen variable and then 
displays the name of that screen in the Output panel: 

var myScreen = fl . getDocumentDOM( ). screenOutl i ne . currentScreen ; 
fl . trace ( my Screen. name) ; 

screenOutline.deleteScreen() 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . del eteScreen ( [screenName] ) 
Parameters 

screenName A string that specifies the name of the screen to be deleted. If you don't pass a value 
for screenName, the currently selected screen(s) and their children are deleted. This parameter is 
optional. 

Returns 

Nothing. 
Description 

Method; deletes the currently selected screen(s), or a specified screen, and the children of the 
screen (s). 

Example 

The following example removes the screen named apple and all its children: 

f 1 . get Document DOM ( ). screenOutl ine.deleteScreen(" apple"); 
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screenOutline.duplicateScreenQ 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . dupl i cateScreen ( [screenName^ ) 
Parameters 

screenName A string value that specifies the screen name to duplicate. If you don't pass a value 
for screenName, the currently selected screen(s) are duplicated. This parameter is optional. 

Returns 

A Boolean value: true if the screen is successfully duplicated; fal se otherwise. 
Description 

Method; duplicates the currently selected screen(s) or a specified screen. The duplicate screens are 
given a default name by appending _copy to the original name, such as Screen_copy, 
Screen_copy2, and so on. If you duplicate multiple screens, the duplicates are placed directly 
below the selected screen that is lowest in the screen outline hierarchy. 

Example 

The following example duplicates a screen named apple: 

f 1 . getDocumentDOM( ). screenOutl ine.duplicateScreen(" apple"); 

screenOutline.getSelectedScreens() 

Availability 

Flash MX 2004. 
Usage 

screenOutl ine.getSelectedScreensO 
Parameters 

None. 
Returns 

An array of selected Screen objects (see Screen object). 
Description 

Method; returns an array of Screen objects that are currently selected in the screen outline. 
Example 

The following example stores the selected Screen objects in the myArray variable and displays the 
screen names in the Output panel: 

var myArray = fl . getDocumentDOM( ). screenOutl i ne . getSel ectedScreens () ; 
for (var i in myArray) j 
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fl . trace(myArray [i ] . name) 

} 



screenOutline.insertNestedScreen() 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . i nsertNestedScreen( [ name [, referenceScreen [, screenTypeName 
1 1 ]) 

Parameters 

name A string indicating the name of the new screen to insert. An empty name will insert a 
screen with a default screen name, such as Slide n or Form n (where n is the first available unique 
number). This parameter is optional. 

The optional referenceScreen parameter is a string indicating the name of the screen into 
which the new screen is inserted as a child. If this parameter is not specified, the new screen is 
inserted as a child of the currently selected screen. 

The optional screenTypeName parameter is a string that specifies the name of the screen type to 
attach to the new nested screen. The screen type and classname will be set for this screen. If this 
parameter is not specified, the type is inherited from the parent screen. Acceptable values are 
" Form" and "SI i de". 

Returns 

A Screen object. 
Description 

Method; inserts a nested screen of a specific type into a particular location in the screen outline. 
Example 

The following example inserts slide2 as a child of slide 1: 

f 1 . ge t Document DOM ( ). screenOutl ine.insertNestedScreen(" si ide2", "si i del " , 
"Slide"); 

screenOutline.insertScreen() 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . i nsertScreen ( [name [, referenceScreen [, screenTypeName ] ] ]) 
Parameters 

name A string indicating the name of the new screen to insert. If this parameter is omitted, the 
method inserts a screen with a default screen name, such as Slide n or Form n (where n is the first 
available unique number). This parameter is optional. 
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referenceScreen A string indicating the name of the screen before the new screen. If this 
parameter is omitted, the new screen is inserted after the currently selected screen. If the 
referenceScreen parameter identifies a child screen, the new screen will be a peer of the child 
screen, and a child screen of the same parent. This parameter is optional. 

screen TypeName A string that specifies the screen type to attach to the new screen. The screen 
type and classname are set for this screen. Acceptable values are " Form" and "SI i de". This 
parameter is optional. 

Returns 

A Screen object. 
Description 

Method; inserts a new blank screen of a specified type into the document at a specified location. 
Example 

The following example inserts a form named slide2 after the screen named slide 1: 

f 1 . getDocumentDOM( ) . screenOutl i ne . i nsert Screen ( "si i de2" , "si i del " , " Form" ) ; 

The following example inserts a slide named slide4 after the screen slide3: 

f 1 . get Document DOM ( ) . screenOutl i ne . i nsert Screen ( "si i de4" , "si i de3" , " SI i de" ) ; 

screenOutline.moveScreen() 

Availability 

Flash MX 2004. 
Usage 

screenOutl ine.moveScreen( screenToMove, referenceScreen, position ) 
Parameters 

screenfoMove A string that is the screen name to move. 

referenceScreen A string that specifies the screen near which screenToMove will be placed. 

position A string that specifies where to move the screen in relation to referenceScreen. 
Acceptable values are "bef ore","af ter","f i rstChi 1 d", or " 1 astChi 1 d". 

Returns 

A Boolean value: true if the move is successful; false otherwise. 
Description 

Method; moves the specified screen in relation to the value of the referenceScreen parameter; 
either before, after, as the first child, or as the last child. 
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Example 

The following example moves screen slidel to be the first child of slide2: 

fl . get Document DOM ( ). screenOutl ine. mo veScreen("slidel", "slide2", 
"firstChild"); 

screenOutline.renameScreen() 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . renameScreen ( newScreenName [, ol dScreenName [, bDi spl ay Errors ] 
) 

Parameters 

newScreenName A string that specifies the new name of the screen 

ol dScreenName A string that specifies the name of the existing screen to change. If not 
specified, the name of the currently selected screen changes. This parameter is optional. 

bDi spl ay Error A Boolean value that, if set to true, shows an error message if an error occurs, 
for example, if a screen with the same name as the value passed to newScreenName already exists. 
The default value is false. 

Returns 

A Boolean value: true if the renaming is successful; false otherwise. 
Description 

Method; changes the screen with a specified name to a new name. 
Example 

The following example changes the name of slidel to Intro: 

f 1 . getDocumentDOM( ). screenOutl ine. rename Screen(" Intro", "slidel"); 

screenOutline.rootScreen 

Availability 

Flash MX 2004. 
Usage 

screenOutline.rootScreen 
Description 

Read-only property; the first screen in the screen outline. You can use 

screenOutline.rootScreen as a shortcut for screenOutl ine. screens [0]. 
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Example 

The following example displays the name of the first child of the first screen in the screen outline: 
fl . trace(f 1 . ge t Document DOM ( ) .screenOutl ine.rootScreen.childScreens[0] .name) ; 

screenOutline.screens 

Availability 

Flash MX 2004. 

Usage 

screenOutline.screens 

Description 

Read-only property; the array of top level Screen objects contained in the document (see Screen 
object). 

Example 

The following example stores the array of Screen objects in the myArray variable and then 
displays their names in the Output panel: 

var myArray = new ArrayU; 

i f ( f 1 . get Document DOM ( hallowScreens) { 

for(var i in fl . getDocumentDOMt ). screenOutl i ne . screens ) { 

myArray . push ( " "+f 1 . get Document DOM ( ) .screenOutl i ne.screens[i ] .name) ; 

I 

f 1 . tracet "The screens array contains objects whose names are: "+myArray+". 
"); 

} 

screenOutline.setCurrentScreen() 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . setCurrentScreen ( name ) 
Parameters 

name A string that specifies the name screen which should become the currently selected screen. 
If the screen is a child of another screen, you do not need to indicate a path or hierarchy. 

Returns 

Nothing. 
Description 

Method; sets the current selection in the screen outline to the specified screen. 
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Example 

The following example sets the current screen to the screen named ChildOfSlide_l: 

f 1 . getDocumentDOM( ).screenOutline.setCurrentScreen("ChildOfSli de_l " ) ; 

screenOutline.setScreenPropertyO 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . setScreenProperty ( property, value ) 
Parameters 

property A string that specifies the property to set. 

va 1 ue The new value for the property. The type of value depends on the property being set. 

For a list of available properties and values, see Property summary for the Screen object. 
Returns 

Nothing. 
Description 

Method; sets the specified property with the specified value for the selected screens. 
Example 

The following example changes the visibility of the currently selected screens from hidden to 
visible: 

fl . getDocumentDOM( ). screenOutl ine. setScreenProperty ("hidden", false); 

screenOutline.setSelectedScreens() 

Availability 

Flash MX 2004. 
Usage 

screenOutl i ne . setSel ectedScreens ( selection [, bRepl aceCurrentSel ecti on ] ) 
Parameters 

sel ecti on An array of screen names to be selected in the screen outline. 

bRepl aceCurrentSel ecti on A Boolean value that, if true, lets you deselect the current 
selection. The default value is true. If f al se, Flash extends the current selection to include the 
specified screens. This parameter is optional. 

Returns 

Nothing. 
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Description 

Method; selects the specified screens in the screen outline. If multiple screens are specified, the 
screen with the last index value of the selection array is focused on the Stage. 

Example 

The following example deselects any currently selected screens, and then selects screens s 1 i d e 1 , 
si i de2, si i de3, and slide4 in the screen outline: 

myArray = new Array ( "si idel" , "slide2", "slide3", "slide4"); 

f 1 . get Document DOM ( J.screenOutline.setSel ectedScreens (myArray , true ) ; 
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Shape object 

Inheritance Element object > Shape object 
Availability 

Flash MX 2004. 
Description 

The Shape object is a subclass of the Element object. The Shape object provides more precise 
control than the Drawing APIs when manipulating or creating geometry on the Stage. This 
control is necessary so that scripts can create useful effects and other drawing commands. 

All Shape methods and properties that change a shape or any of its subordinate parts must be 
placed between shape, beg i n Ed i t ( ) and shape, end Ed it( ) calls to function correctly. 

Method summary for the Shape object 

In addition to the Element object methods, you can use the following methods with the 
Shape object: 



Method 


Description 


shape . begi n Ed i t ( ) 


Method; defines the start of an edit session. 


shape . del eteEdge( ) 


Method; deletes the specified edge. 


shape . endEdi t ( ) 


Method; defines the end of an edit session for the shape. 



Property summary for the Shape object 



In addition to the Element object properties, the following properties are available for the 



Shape object: 


Property 


Description 


shape . contours 
shape . edges 
shape . i sGroup 
shape . verti ces 


Read-only; an array of Contour objects for the shape (see Contour object). 

Read-only; an array of Edge objects (see Edge object). 

Read-only; if true, the shape is a group. 

Read-only; an array of Vertex objects (see Vertex object). 



shape. beginEdit() 

Availability 

Flash MX 2004. 

Usage 

shape . begi nEdi t ( ) 

Parameters 

None. 
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Returns 

Nothing. 
Description 

Method; defines the start of an edit session. You must use this method before issuing any 
commands that change the Shape object or any of its subordinate parts. 

Example 

The following example takes the currently selected shape and removes the first edge in the edge 
array from it: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
shape . begi nEdi t ( ) ; 
shape. del eteEdge(O) ; 
shape . endEdi t ( ) ; 

shape.contours 

Availability 

Flash MX 2004. 

Usage 

shape . contours 

Description 

Read-only property; an array of Contour objects for the shape (see Contour object). 
Example 

The following example stores the first contour in the contours array in the c variable and then 
stores the HalfEdge object of that contour in the he variable: 

var c = fl . getDocumentDOM( ). sel ecti on [0] . contours [0] ; 
var he = c . getHal f Edge ( ) ; 

shape.deleteEdge() 

Availability 

Flash MX 2004. 
Usage 

shape. del eteEdge( index ) 
Parameters 

index A zero-based index that specifies the edge to delete from the shape, edges array. This 
method changes the length of the shape, edges array. 

Returns 

Nothing. 
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Description 

Method; deletes the specified edge. You must call shape, beg i n Ed i t { ) before using this method. 
Example 

The following example takes the currently selected shape and removes the first edge in the edge 
array: 

var shape = f 1 . getDocumentDOM( ) . sel ecti on [0] ; 
shape . begi nEdi t ( ) ; 
shape. del ete Ed ge( 0 ) ; 
shape . endEdi t ( ) ; 

shape.edges 

Availability 

Flash MX 2004. 

Usage 

shape . edges 

Description 

Read-only property; an array of Edge objects (see Edge object). 

shape.endEdit() 

Availability 

Flash MX 2004. 

Usage 

shape. endEditt ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; defines the end of an edit session for the shape. All changes made to the Shape object or 
any of its subordinate parts will be applied to the shape. You must use this method after issuing 
any commands that change the Shape object or any of its subordinate parts. 

Example 

The following example takes the currently selected shape and removes the first edge in the edge 
array from it: 

var shape = f 1 . getDocumentD0M( ) . sel ecti on [0] ; 
shape . begi nEdi t ( ) ; 
shape. del eteEdge(O); 
shape . endEdi t ( ) ; 
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shape. isGroup 

Availability 

Flash MX 2004. 

Usage 

shape . i sGroup 

Description 

Read-only property; if true, the shape is a group. 
Example 

The following example stores the first selected item object in the sel variable and then uses the 
el ement . el ementType and shape . i sGroup properties to test if the selected item is a group: 

var sel = f 1 . getDocumentDOMt ) . sel ecti on [0] ; 

var theShapelsReal lyAGroup = ( sel . el ementType == "shape") && sel . i sGroup ; 

shape.vertices 

Availability 

Flash MX 2004. 

Usage 

shape . verti ces 

Description 

Read-only property; an array of Vertex objects (see Vertex object). 
Example 

The following example stores the first selected i tern object in the someShape variable and then 
shows the number of vertices for that object in the Output panel: 

var someShape = f 1 . getDocumentD0M( ) . sel ecti on [0] ; 

f 1 . trace( "The shape has " + someShape . verti ces . 1 ength + " vertices."); 
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Soundltem object 

Inheritance Item object > Soundltem object 
Availability 

Flash MX 2004. 
Description 

The Soundltem object is a subclass of the Item object. It represents a library item used to create a 
sound. See also frame . sound Li bra ry I tern. 

Property summary for the Soundltem object 

In addition to the Item object properties, the following properties are available for the 
Soundltem object: 

Property Description 

soundltem. bit Rate A string that specifies the bit rate of a sound in the library. 

Available only for the MP3 compression type. 

sound Item .bits A string that specifies the bits value for a sound in the library that 

has ADPCM compression. Acceptable values are "2 bit", "3 
bit", "4 bit", and "5 bi t" when the type of compression is 
ADPCM. 

soundltem. compressi onType A string that specifies that compression type for a sound in the 

library. Acceptable values are "Def aul t", "ADPCM", "MP3", "Raw", 
and "Speech". 

soundltem. convertStereoToMono A Boolean value available only for MP3 and Raw compression 

types. 

soundltem.qual i ty A string that specifies the playback quality of a sound in the 

library. Available only for MP3 compression type. 

soundltem. sampl eRate Available only for ADPCM, Raw, and Speech compression 

types. 

soundltem. use Import edMP3Qual i ty A Boolean value; if true, all other properties are ignored and the 

imported MP3 quality is used. 

soundltem. bitRate 

Availability 

Flash MX 2004. 

Usage 

soundltem. bitRate 
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Description 

Property; a string that specifies the bit rate of a sound in the library. This property is available 
only for the MP3 compression type. Acceptable values are "8kbps", "16kbps", "20kbps", 
"24kbps", "32kbps", "48kbps", "56kbps", "64kbps", "80kbps", "112kbps", "128kbps", and 
"160kbps". The property is undef i ned for other compression types. 

Note: When an MP3 is imported to the library, the Use imported MP3 quality Export setting is 
checked by default. The bi tRate property cannot be set with this setting checked. 

Example 

The following example displays the bi tRate value in the Output panel if the specified item in the 
library has MP3 compression type: 

al ert (f 1 . get Document DOM ( ) . 1 i brary . i terns [0] . bi tRate ) ; 

soundltem.bits 

Availability 

Flash MX 2004. 

Usage 

soundltem. bi ts 

Description 

Property; a string that specifies the bits value for a sound in the library that has ADPCM 
compression. Acceptable values are " 2 bit", "3 bit", "4 bit", and "5 bit". 

Example 

The following example displays the bits value in the Output panel if the currently selected item in 
the library has ADPCM compression type: 

al ert ( f 1 . get Document DOM ( ). li brary. it ems[0]. bits); 

soundltem. compressionType 

Availability 

Flash MX 2004. 
Usage 

soundltem. compressi onType 
Description 

Property; a string that specifies that compression type for a sound in the library. Acceptable values 
are "Default", "ADPCM", "MP3", "Raw", and "Speech". 

Example 

The following example changes an item in the library to compression type Raw: 

f 1 . getDocumentD0M( ) . 1 i brary . i terns [0] . compressi onType = " Raw" ; 
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The following example changes a selected item's compression type to Speech: 

f 1 . ge t Document DOM ( hlibrary.getSel ectedl terns ( ) [0] . compressi onType = "Speech"; 

soundltem.convertStereoToMono 

Availability 

Flash MX 2004. 
Usage 

soundltem.convertStereoToMono 
Description 

Property; a Boolean value available only for MP3 and Raw compression types. Setting this to 
true converts a stereo sound to mono; false leaves it as stereo. For MP3 compression type, if 
soundltem.bitRate is less than 20 Kbps, this property is ignored and forced to true. 

Example 

The following example converts an item in the library to mono, only if the item has MP3 or Raw 
compression type: 

f 1 . get Document DOM ( ) . 1 i brary . i terns [0] . convertStereoToMono = true ; 

soundltem. quality 

Availability 

Flash MX 2004. 

Usage 

soundltem. qual ity 

Description 

Property; a string that specifies the playback quality of a sound in the library. This property is 
available only for MP3 compression type. Acceptable values are "Fast", "Medium", "Best". 

Example 

The following example sets the playback quality of an item in the library to Best, if the item has 
MP3 compression type: 

fl . getDocumentD0M( ). 1 i bra ry . i terns [0] . qual i ty = "Best"; 

soundltem.sampleRate 

Availability 

Flash MX 2004. 

Usage 

soundltem. sample Rate 
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Description 

Property; available only for ADPCM, Raw, and Speech compression types. This value sets the 
sample rate for the audio clip. Acceptable values are " 5 k H z " , " 1 1 k H z " , " 2 2 kHz", and " 4 4 
kHz". 

Note: When an MP3 is imported to the library, the Use imported MP3 quality Export setting is 
checked by default. The sampleRate property cannot be set with this setting checked. 

Example 

The following example sets the sample rate of an item in the library to 5 kHz, if the item has 
ADPCM, Raw, or Speech compression type: 

fl . getDocumentDOMt ). 1 i brary . i terns [0] . sampl eRate = "5 kHz"; 

soundltem.uselmportedMP3Quality 

Availability 

Flash MX 2004. 
Usage 

soundItem.useImportedMP3Quality 
Description 

Property; a Boolean value. If true, all other properties are ignored and the imported MP3 quality 
is used. 

Example 

The following example sets an item in the library to use the imported MP3 quality: 

f 1 . getDocumentDOMt ) . 1 i brary . i terns [0] .useImportedMP3Quality = true; 
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Stroke object 



Availability 

Flash MX 2004. 
Description 

The Stroke object contains all the settings for a stroke, including the custom settings. This object 
represents the information contained in the Stroke Properties inspector. Using the Stroke object 
together with the document.setCustomStroke( ) method, you can change the stroke settings for 
the toolbar, the Properties Inspector, and the current selection. You can also get the stroke settings 
of the toolbar and Properties Inspector, or of the current selection, by using the 
document . getCustomStroke ( ) method. 

This object always has the following four properties: styl e, thi ckness, col or, and 
breakAtCorners. Other properties can be set, depending on the value of the styl e property. 

Property summary for the Stroke object 

The following properties are available for the Stroke object: 

Property Description 

stroke. breakAtCorners Same as the Sharp Corners setting in the custom Stroke Style dialog box. 

stroke, col or A color string in hexadecimal (#rrggbb) format or an integer containing the 

value. 



stroke 


.curve 


A string that specifies type of hatching for the stroke. 


stroke 


.dashl 


An integer that specifies the lengths of the solid part of a dashed line. 


stroke 


.dashZ 


An integer that specifies the lengths of the blank part of a dashed line. 


stroke 


.density 


A string that specifies the density of a stippled line. 


stroke 


dotSi ze 


A string that specifies the dot size of a stippled line. 


stroke 


.dotSpace 


An integer that specifies the spacing between dots in a dotted line. 


stroke 


. hatchThi ckness 


A string that specifies the thickness of a hatch line. 


stroke 


jiggle 


A string that specifies the jiggle property of a hatched line. 


stroke 


. 1 ength 


A string that specifies the length of a hatch line. 


stroke 


.pattern 


A string that specifies the pattern of a ragged line. 


stroke 


rotate 


A string that specifies the rotation of a hatch line. 


stroke 


.space 


A string that specifies the spacing of a hatched line. 


stroke 


style 


A string that describes the stroke style. 


stroke 


.thickness 


An integer that specifies the stroke size. 


stroke 


variation 


A string that specifies the variation of a stippled line. 
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Property 



Description 



stroke. waveHeight 



A string that specifies the wave height of a ragged line. 



stroke. wavetength 



A string that specifies the wave length of a ragged line. 



stroke. breakAtCorners 

Availability 

Flash MX 2004. 

Usage 

stroke . breakAtCorners 

Description 

Property; a Boolean value. This property is the same as the Sharp Corners setting in the custom 
Stroke Style dialog box. 

Example 

The following example sets the breakAtCorners property to true: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

myStroke. breakAtCorners = true; 

f 1 . getDocumentDOMt ) . setCustomStroke( myStroke ); 

stroke.color 

Availability 

Flash MX 2004. 

Usage 

stroke . col or 

Description 

Property; a color string in hexadecimal (#rrggbb) format or an integer containing the value. This 
property represents the stroke color. 

Example 

The following example sets the stroke color: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
myStroke. color = "#000000"; 

fl . getDocumentDOMt ). setCustomStroke( myStroke ); 

stroke. curve 

Availability 

Flash MX 2004. 

Usage 

stroke . curve 
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Description 

Property; a string that specifies type of hatching for the stroke. This property can be set only if 
stroke. style property is "hatched". Acceptable values are "straight", "slight curve", 
"medium curve", and "very curved". 

Example 

The following example sets the curve property, as well as others, for a stroke having the 
"hatched" style: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
mySt roke . sty 1 e = "hatched"; 
myStroke. curve = "straight"; 
myStroke. space = "close" 
mySt roke . j i ggl e = "wild" 
myStroke. rotate = "free": 
myStroke . 1 ength = "slight"; 
myStroke . hatchThi ckness = "thin"; 
f 1 . getDocumentDOMt ) . setCustomStroke( myStroke ); 

stroke. dashl 

Availability 

Flash MX 2004. 

Usage 

stroke. dashl 

Description 

Property; an integer that specifies the lengths of the solid parts of a dashed line. This property is 
available only if the stroke . styl e property is set to "dashed". 

Example 

The following example sets the dashl and dash2 properties for a stroke style of dashed: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
myStroke . sty 1 e = "dashed"; 
myStroke. dashl = 1 ; 
myStroke. dash2 = 2; 

fl . getDocumentDOMt ). setCustomStroke( myStroke ); 

stroke. dash2 

Availability 

Flash MX 2004. 

Usage 

stroke. dash2 
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Description 

Property; an integer that specifies the lengths of the blank parts of a dashed line. This property is 
available only if the stroke . sty 1 e property is set to "dashed". 

Example 

See stroke . dashl. 

stroke. density 

Availability 

Flash MX 2004. 

Usage 

stroke. density 

Description 

Property; a string that specifies the density of a stippled line. This property is available only if the 
stroke. style property is set to "stipple". Acceptable values are "very dense", "dense", 
"sparse", and "very sparse". 

Example 

The following example sets the density property to "sparse" for the stroke style of sti ppl e: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

myStroke . sty 1 e = "stipple"; 

myStroke. dotSpace= 3; 

myStroke. variation = "random sizes"; 

myStroke. density = "sparse"; 

f 1 . getDocumentDOMt ) . setCustomStroke( myStroke ); 

stroke. dotSize 

Availability 

Flash MX 2004. 

Usage 

stroke . dotSi ze 

Description 

Property; a string that specifies the dot size of a stippled line. This property is available only if the 
st roke . sty 1 e property is set to "sti ppl e". Acceptable values are "ti ny", "small", "medium", 
and "1 arge". 

The following example sets the dotsi ze property to "ti ny " for the stroke style of sti ppl e: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
myStroke . sty 1 e = "stipple"; 
myStroke. dotSpace= 3; 
myStroke. dotsize = "tiny"; 
myStroke. variation = "random sizes"; 
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myStroke. density = "sparse"; 

f 1 . getDocumentDOM( ) . setCustomStroke( myStroke ); 

stroke. dotSpace 

Availability 

Flash MX 2004. 

Usage 

stroke .dotSpace 

Description 

Property; an integer that specifies the spacing between dots in a dotted line. This property is 
available only if the stroke . sty 1 e property is set to "dotted". 

Example 

The following example sets the dotSpace property to 3 for a stroke style of dotted: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
myStroke . sty 1 e = "dotted"; 
myStroke. dotSpace= 3; 

f 1 . getDocumentDOM( ) . setCustomStroke( myStroke ); 

stroke. hatchThickness 

Availability 

Flash MX 2004. 

Usage 

stroke. hatchThickness 

Description 

Property; a string that specifies the thickness of a hatch line. This property is available only if the 
stroke. style property is set to "hatched". Acceptable values are "hairline", "thin", 
"medi urn", and "thi ck". 

Example 

The following example sets the hatchThickness property to "thin" for a stroke style of 

hatched: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

myStroke . sty 1 e = "hatched"; 

myStroke. curve = "straight"; 

myStroke . space = "close"; 

myStroke . j i ggl e = "wild"; 

myStroke. rotate = "free"; 

myStroke. 1 ength = "slight"; 

myStroke . hatchThi ckness = "thin"; 

f 1 . getDocumentDOMt ) . setCustomStroke( myStroke ); 
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stroke.jiggle 

Availability 

Flash MX 2004. 

Usage 

stroke . j i ggl e 

Description 

Property; a string that specifies the jiggle property of a hatched line. This property is available 
only if the stroke. style property is set to "hatched". Acceptable values are "none", "bounce", 
" 1 oose", and "wi Id". 

Example 

The following example sets the jiggle property to "wild" for a stroke style of hatched: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

mySt roke . sty 1 e = "hatched"; 

myStroke. curve = "straight"; 

myStroke . space = "close"; 

myStroke . j i ggl e = "wild"; 

myStroke. rotate = "free"; 

myStroke . 1 ength = "slight"; 

myStroke . hatchThi ckness = "thin"; 

f 1 . getDocumentDOMt ) . setCustomStroke( myStroke ); 

stroke. length 

Availability 

Flash MX 2004. 

Usage 

stroke . 1 ength 

Description 

Property; a string that specifies the length of a hatch line. This property is available only if the 
stroke. style property is set to "hatched". Acceptable values are "equal ", "slight", 
"variation", "medi urn variation", and "random". 

Example 

The following example sets the 1 ength property to "si i ght" for a stroke style of hatched: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

myStroke . sty 1 e = "hatched"; 

myStroke. curve = "straight"; 

myStroke. space = "close"; 

myStroke . j i ggl e = "wild"; 

myStroke . rotate = "free"; 

myStroke . 1 ength = "slight"; 

myStroke . hatchThi ckness = "thin"; 

f 1 . getDocumentDOM( ) . setCustomStroke( myStroke ); 
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stroke. pattern 

Availability 

Flash MX 2004. 

Usage 

stroke . pattern 

Description 

Property; a string that specifies the pattern of a ragged line. This property is available only if the 
stroke. style property is set to "ragged". Acceptable values are "sol i d", "si mpl e", "random", 
"dotted", "random dotted", "tri pi e dotted", and "random triple dotted". 

Example 

The following example sets the pattern property to "random" for a stroke style of ragged: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
mySt roke . sty 1 e = "ragged"; 
myStroke. pattern = "random"; 

fl . getDocumentDOMt ). setCustomStroke( myStroke ); 

stroke. rotate 

Availability 

Flash MX 2004. 

Usage 

stroke . rotate 

Description 

Property; a string that specifies the rotation of a hatch line. This property is available only if the 
stroke. style property is set to "hatched". Acceptable values are "none", "si i ght ", "medi urn", 
and "free". 

Example 

The following example sets the rotate property to "free" for a style stroke of hatched: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

myStroke . sty 1 e = "hatched"; 

myStroke. curve = "straight"; 

myStroke. space = "close"; 

myStroke . j i ggl e = "wild"; 

myStroke . rotate = "free"; 

myStroke . 1 ength = "slight"; 

myStroke . hatchf hi ckness = "thin"; 

fl . getDocumentDOMt ). setCustomStroke( myStroke ); 
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stroke.space 

Availability 

Flash MX 2004. 

Usage 

stroke .space 

Description 

Property; a string that specifies the spacing of a hatched line. This property is available only if the 
stroke. style property is set to "hatched". Acceptable values are "very close", "close", 
"distant", and "very distant". 

Example 

The following example sets the space property to "cl ose" for a stroke style of hatched: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

mySt roke . sty 1 e = "hatched"; 

myStroke. curve = "straight"; 

myStroke . space = "close"; 

myStroke . j i ggl e = "wild"; 

myStroke. rotate = "free"; 

myStroke . 1 ength = "slight"; 

myStroke . hatchThi ckness = "thin"; 

f 1 . getDocumentDOMt ) . setCustomStroke( myStroke ); 

stroke.style 

Availability 

Flash MX 2004. 

Usage 

stroke . styl e 

Description 

Property; a string that describes the stroke style. Acceptable values are "noStroke" , "solid", 
"dashed", "dotted", "ragged", "stipple", and "hatched". Some of these values require 
additional properties of the stroke object to be set, as described in the following list: 

• If value is "sol id" or "noStroke" , there are no other properties. 

• Ifvalueis "dashed", there are two additional properties: "dashl" and "dash2". 

• Ifvalueis "dotted", there is one additional property: "dotSpace". 

• Ifvalueis "ragged", there are three additional properties: "pattern", "waveHei ght", and 
"waveLength". 

• If value is "stipple", there are three additional properties: " d o t S i z e " , "variation", and 
"densi ty". 

• Ifvalueis "hatched", there are six additional properties: " hatchThi ckness ", "space", 
"jiggle", "rotate", "curve", and "length". 
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Example 

The following example sets the stroke style to "ragged": 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
mySt roke . sty 1 e = "ragged"; 

f 1 . getDocumentDOMt ) . setCustomStroke( myStroke ); 

stroke.thickness 

Availability 

Flash MX 2004. 

Usage 

stroke . thi ckness 

Description 

Property; an integer that specifies the stroke size. 
Example 

The following example sets the thickness property of the stroke to a value of 2 : 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 
myStroke. thickness = 2; 

f 1 . getDocumentDOM( ) . setCustomStroke( myStroke ); 

stroke.variation 

Availability 

Flash MX 2004. 

Usage 

stroke . va ri ati on 

Description 

Property; a string that specifies the variation of a stippled line. This property is available only if 
the stroke. style property is set to "stipple". Acceptable values are "one si ze", "smal 1 
va ri ati on", " vari ed sizes", and "random sizes". 

Example 

The following example sets the variation property to "random sizes" for a stroke style of 

st i ppl e: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

myStroke . sty 1 e = "stipple"; 

myStroke. dotSpace= 3; 

myStroke. variation = "random sizes"; 

myStroke. density = "sparse"; 

fl . getDocumentDOMt ). setCustomStroke( myStroke ); 
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stroke.waveHeight 

Availability 

Flash MX 2004. 

Usage 

stroke.waveHeight 

Description 

Property; a string that specifies the wave height of a ragged line. This property is available only if 
the stroke . styl e property is set to " ragged". Acceptable values are "flat", "wavy", "very 
wavy", and "wi Id". 

Example 

The following example sets the waveHei ght property to "f 1 at" for a stroke style of ragged: 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

mySt roke . sty 1 e = "ragged"; 

myStroke. pattern = "random"; 

myStroke. waveHeight = "flat"; 

myStroke. waveLength = "short"; 

f 1 . getDocumentDOM( ) . setCustomStroke( myStroke ); 

stroke.waveLength 

Availability 

Flash MX 2004. 

Usage 

stroke.waveLength 

Description 

Property; a string that specifies the wave length of a ragged line. This property is available only if 
the stroke. style property is set to "ragged". Acceptable values are "very short", "short", 
"medi urn", and "1 ong". 

Example 

The following example sets the waveLength property to "short" for a stroke style of ragged : 

var myStroke = fl . getDocumentDOM( ) .getCustomStroke( ) ; 

myStroke . sty 1 e = "ragged"; 

myStroke. pattern = "random"; 

myStroke. waveHeight = 'flat"; 

myStroke. waveLength = "short"; 

f 1 . getDocumentDOM( ) . setCustomStroke( myStroke ); 
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Symbollnstance object 

Inheritance Element object > Instance object > Symbollnstance object 
Availability 

Flash MX 2004. 
Description 

Symbollnstance is a subclass of the Instance object and represents a symbol in a frame. 

Property summary for the Symbollnstance object 

In addition to the Instance object properties, the Symbollnstance object has the following 
properties: 

Property Description 

symbol Instance . accName A string that is equivalent to the Name field in the Accessibility 

panel. 

symbol Instance . acti onScri pt A string that specifies the actions assigned to the symbol. 

symbol Instance.buttonTracki ng A string that, for button symbols only, sets the same property 

as the pop-up menu for Track as Button or Track as Menu 
Item in the Property inspector. 

symbol Instance . col orAl phaAmount An integer that is part of the color transformation for the 

instance, specifying the Advanced Effect Alpha settings; 
equivalent to using the Color > Advanced setting in the 
Property inspector and adjusting the controls on the right of 
the dialog box. 

symbol Instance, col orAlphaPercent An integer that specifies part of the color transformation for 

the instance; equivalent to using the Color > Advanced setting 
in the Instance Property inspector (the percentage controls on 
the left of the dialog box). 

symbol Instance, col orBl ueAmount An integer that is part of the color transformation for the 

instance; equivalent to using the Color > Advanced setting in 
the Instance Property inspector. 

symbol Instance, col orBluePercent An integer that is part of the color transformation for the 

instance; equivalent to using the Color > Advanced setting in 
the Instance Property inspector (the percentage controls on 
the left of the dialog box). 

symbol Instance . col orGreen Amount An integer that is part of the color transformation for the 

instance; equivalent to using the Color > Advanced setting in 
the Instance Property inspector. Allowable values are from - 
255 to 255. 

symbol Instance . col orGreen Percent Part of the color transformation for the instance; equivalent to 

using the Color > Advanced setting in the Instance Property 
inspector (the percentage controls on the left of the dialog 
box). 
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Property 



Description 



symbol Instance . col orMode 
symbol Instance . col orRedAmount 

symbol Instance . col orRedPercent 

symbol Instance. descript ion 
symbol Instance.fi rstFrame 
symbol Instance. forces imple 

symbol Instance . 1 oop 
symbol Instance. shortcut 

symbol Instance. si lent 

symbol Instance . symbol fype 

symbol Instance. tablndex 



A string that specifies the color mode as identified in the 
symbol Property inspector Color pop-up menu. 

An integer that is part of the color transformation for the 
instance, equivalent to using the Color > Advanced setting in 
the Instance Property inspector. 

Part of the color transformation for the instance; equivalent to 
using the Color > Advanced setting in the Instance Property 
inspector (the percentage controls on the left of the dialog 
box). 

A string that is equivalent to the Description field in the 
Accessibility panel. 

A zero-based integer that specifies the first frame to appear in 
the Timeline of the graphic. 

A Boolean value that enables and disables the accessibility of 
the object's children; equivalent to the inverse logic of the 
Make Child Objects Accessible setting in the Accessibility 
panel. 

A string that, for graphic symbols, sets the same property as 
the Loop pop-up menu in the Property inspector. 

A string that is equivalent to the shortcut key associated with 
the symbol; equivalent to the Shortcut field in the Accessibility 
panel. 

A Boolean value that enables or disables the accessibility of 
the object; equivalent to the inverse logic of the Make Object 
Accessible setting in the Accessibility panel. 

A string that specifies the type of symbol; equivalent to the 
value for Behavior in the Create New Symbol and Convert To 
Symbol dialog boxes. 

An integer that is equivalent to the Tab index field in the 
Accessibility panel. 



symbollnstance.accName 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. accName 
Description 

Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers 
identify objects by reading the name aloud. This property is not available for graphic symbols. 



Symbollnstance object 285 



Example 

The following example stores the value for the Accessibility panel name of the object in the 
theName variable: 

var theName = f 1 . getDocumentDOM( ) . sel ecti on [0] . accName ; 

The following example sets the value for the Accessibility panel name of the object to "Home 
Button": 

fl . getDocumentDOM( ). sel ecti on[0] . accName = "Home Button"; 

symbollnstance.actionScript 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. act ionScript 
Description 

Property; a string that specifies the actions assigned to the symbol. This applies only to movie clip 
and button instances. For a graphic symbol instance, the value returns undefined. 

Example 

The following example assigns anonClipEvent action to the first item in the first frame of the 
first layer in the Timeline: 

f 1 . get Document DOM ( ).getTimeline().layers[0].frames[0].el ements [0] .act ionScript 
= "onCl ipEvent(enterFrame) jtrace( 'movie clip enterFrame ' ) ; I " ; 

symbollnstance.buttonTracking 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. buttonTracking 
Description 

Property; a string that, for button symbols only, sets the same property as the pop-up menu for 
Track as Button or Track as Menu Item in the Property inspector. For other types of symbols, this 
property is ignored. Acceptable values are "button" or "menu". 

Example 

The following example sets the first symbol in the first frame of the first layer in the Timeline to 
Track as Menu Item, as long as that symbol is a button: 

f 1 . get Document DOM ( ) . getTimel i ne( ) . 1 ayers [0] . f rames [0] . el ements [0] .buttonTracki 
ng = "menu" ; 
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symbollnstance.colorAlphaAmount 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col orAl pha Amount 
Description 

Property; an integer that is part of the color transformation for the instance, specifying the 
Advanced Effect Alpha settings. This property is equivalent to using the Color > Advanced setting 
in the Property inspector and adjusting the controls on the right of the dialog box. This value 
either reduces or increases the tint and alpha values by a constant amount. This value is added to 
the current value. This property is most useful if used with 
symbol Instance . col orAl phaPercent. Allowable values are from -255 to 255. 

Example 

The following example subtracts 100 from the alpha setting of the selected symbol instance: 

fl . getDocumentDOM( ). sel ecti on[0] . col orAl phaAmount = -100; 

symbollnstance.colorAlphaPercent 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col orAl phaPercent 
Description 

Property; an integer that specifies part of the color transformation for the instance. This property 
is equivalent to using the Color > Advanced setting in the Instance Property inspector (the 
percentage controls on the left of the dialog box). This value changes the tint and alpha values to 
a specified percentage. Allowable values are from -100 to 100. See also 

symbol Instance. col orAl phaAmount. 

Example 

The following example sets the col orAl phaPercent of the selected symbol instance to 50: 

fl . getDocumentDOMt ). sel ecti on[0] . col orBl uePercent = 80; 

symbollnstance.colorBlueAmount 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col orBl ueAmount 
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Description 

Property; an integer that is part of the color transformation for the instance. This property is 
equivalent to using the Color > Advanced setting in the Instance Property inspector. Allowable 
values are from -255 to 255. 

symbollnstance.colorBluePercent 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col orBluePercent 
Description 

Property; an integer that is part of the color transformation for the instance. This property is 
equivalent to using the Color > Advanced setting in the Instance Property inspector (the 
percentage controls on the left of the dialog box). This value sets the blue values to a specified 
percentage. Allowable values are from -100 to 100. 

Example 

The following example sets the colorBluePercentof the selected symbol instance to 80: 

f 1 . getDocumentD0M( ) . sel ecti on[0] . col orBl uePercent = 80; 

symbollnstance.colorGreenAmount 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col orGreenAmount 
Description 

Property; an integer that is part of the color transformation for the instance. This property is 
equivalent to using the Color > Advanced setting in the Instance Property inspector. Allowable 
values are from -255 to 255. 

symbollnstance.colorGreenPercent 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col orGreenPercent 
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Description 

Property; part of the color transformation for the instance. This property is equivalent to using 
the Color > Advanced setting in the Instance Property inspector (the percentage controls on the 
left of the dialog box). This value sets the green values by a specified percentage. Allowable values 
are from -100 to 100. 

Example 

The following example sets the col orGreenPercent of the selected symbol instance to 70: 

f 1 . getDocumentD0M( ) . sel ecti on[0] . col orGreenPercent = 70; 

symbollnstance.colorMode 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col or Mode 
Description 

Property; a string that specifies the color mode as identified in the symbol Property inspector 
Color pop-up menu. Acceptable values are "none", "brightness", "tint", "alpha", and 
"advanced". 

Example 

The following example changes the col orMode property of the first element in the first frame of 
the first layer in the Timeline to "alpha": 

f 1 . getDocumentD0M( ) . getTimel ine( ) .1 ayers[0] . frame s [0] .el ements [0] .colorMode = 
"alpha"; 

symbollnstance.colorRed Amount 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col orRedAmount 
Description 

Property; an integer that is part of the color transformation for the instance. This property is 
equivalent to using the Color > Advanced setting in the Instance Property inspector. Allowable 
values are from -255 to 255. 

Example 

The following example sets the col orRedAmount of the selected symbol instance to 255: 

fl . getDocumentD0M( ). sel ecti on[0] . col orRedAmount = 255; 
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symbollnstance.colorRedPercent 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. col or RedPercent 
Description 

Property; part of the color transformation for the instance. This property is equivalent to using 
the Color > Advanced setting in the Instance Property inspector (the percentage controls on the 
left of the dialog box). This value sets the red values to a specified percentage. Allowable values are 
from -100 to 100. 

Example 

The following example sets the col orRedPercent of the selected symbol instance to 10: 

f 1 . getDocumentD0M( ) . sel ecti on [0] . col orRedPercent = 10; 

symbollnstance. description 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. description 
Description 

Property; a string that is equivalent to the Description field in the Accessibility panel. The 
description is read by the screen reader. This property is not available for graphic symbols. 

Example 

The following example stores the value for the Accessibility panel description of the object in the 
theDescri pti on variable: 

var theDescri pti on = f 1 . getDocumentD0M( ) . sel ecti on [0] . descri pti on ; 

The following example sets the value for the Accessibility panel description to "Click the home 
button to go to home": 

fl . getDocumentD0M( ). sel ecti on[0] . descri pti on= "Click the home button to go to 
home" ; 

symbollnstance.firstFrame 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. firstFrame 
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Description 

Property; a zero-based integer that specifies the first frame to appear in the Timeline of the 
graphic. This property applies only to graphic symbols and sets the same property as the First field 
in the Property inspector. For other types of symbols, this property is undefined. 

Example 

The following example specifies that Frame 1 1 should be the first frame to appear in the Timeline 
of the specified element: 

f 1 . getDocumentDOM( ) .getTimel ine( ) .1 ayers[0] . frame s [0] .el ements [0] .firstFrame = 
10; 

symbollnstance.forceSimple 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. forceSimple 
Description 

Property; a Boolean value that enables and disables the accessibility of the object's children. This 
property is equivalent to the inverse logic of the Make Child Objects Accessible setting in the 
Accessibility panel. For example, if f orceSi mpl e is true, it is the same as the Make Child Object 
Accessible option being unchecked . If forceSimple is fal se, it is the same as the Make Child 
Object Accessible option being checked. 

This property is available only for movie clip objects. 
Example 

The following example checks to see if the children of the object are accessible; a return value of 
fal se means the children are accessible: 

var a reChi 1 drenAccessi bl e = f 1 . getDocumentD0M( ) . sel ecti on [0] . f orceSi mpl e ; 
The following example allows the children of the object to be accessible: 
fl . getDocumentD0M( ). sel ecti on[0] . f orceSi mpl e = false; 

symbollnstance.loop 

Availability 

Flash MX 2004. 

Usage 

symbol Instance . 1 oop 
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Description 

Property; a string that, for graphic symbols, sets the same property as the Loop pop-up menu in 
the Property inspector. For other types of symbols, this property is undefined. Acceptable values 
are "loop", "play once", and "single frame" to set the graphic's animation accordingly. 

Example 

The following example sets the first symbol in the first frame of the first layer in the Timeline 
to Single Frame (display one specified frame of the graphic Timeline), as long as that symbol is 
a graphic: 

f 1 . ge t Document DOM ( ) . get Time 1 i ne ( ) .1 ayers [0] . frames [0] .el ements [0] .loop = 
' si ngl e frame ' ; 

symbollnstance.shortcut 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. shortcut 
Description 

Property; a string that is equivalent to the shortcut key associated with the symbol. This property 
is equivalent to the Shortcut field in the Accessibility panel. This key is read by the screen readers. 
This property is not available for graphic symbols. 

Example 

The following example stores the value for the shortcut key of the object in the theShortcut 
variable: 

var theShortcut = fl . getDocumentD0M( ). sel ecti on [0] . shortcut ; 
The following example sets the shortcut key of the object to "Ctrl +i ": 
fl . getDocumentD0M( ). sel ecti on[0] . shortcut = "Ctrl+i"; 

symbollnstance.silent 

Availability 

Flash MX 2004. 

Usage 

symbol Instance. si lent 

Description 

Property; a Boolean value that enables or disables the accessibility of the object. This property is 
equivalent to the inverse logic of the Make Object Accessible setting in the Accessibility panel. For 
example, if si 1 en t is true, it is the same as the Make Object Accessible option being unchecked. 
If si 1 ent is f al se, it is the same as the Make Object Accessible option being checked. 
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This property is not available for graphic objects. 
Example 

The following example checks to see if the object is accessible; a return value of fal se means the 
object is accessible: 

var isSilent = f 1 . getDocumentDOM( ) . sel ecti on [0] . si 1 ent ; 

The following example sets the object to be accessible: 

f 1 . getDocumentDOM( ) . sel ecti on[0] . si 1 ent = false; 

symbollnstance.symbolType 

Availability 

Flash MX 2004. 
Usage 

symbol Instance . symbol Type 
Description 

Property; a string that specifies the type of symbol. This property is equivalent to the value for 
Behavior in the Create New Symbol and Convert To Symbol dialog boxes. Acceptable values are 
"button", "movi e clip", and "graphi c". 

Example 

The following example sets the first symbol in the first frame of the first layer in the Timeline of 
the current document to behave as a graphic symbol: 

f 1 . getDocumentDOMt ).getTimeline().layers[0].frames[0].el ements [0] . symbol Type = 
"graphic"; 

symbollnstance.tablndex 

Availability 

Flash MX 2004. 
Usage 

symbol Instance. tablndex 
Description 

Property; an integer that is equivalent to the Tab index field on the Accessibility panel. Creates a 
tab order in which objects are accessed when the user presses the Tab key. This property is not 
available for graphic symbols. 

Example 

The following example sets the tablndex property of the mySymbol object to 3 and displays that 
value in the Output panel: 

var mySymbol = f 1 . getDocumentD0M( ) . sel ecti on [0] ; 

mySymbol . tablndex = 3; 

fl . tracetmySymbol .tablndex) ; 
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Symbolltem object 

Inheritance Item object > Symbolltem object 
Availability 

Flash MX 2004. 
Description 

The Symbolltem object is a subclass of the Item object. 

Method summary for the Symbolltem object 

In addition to the Item object methods, you can use the following methods with the Symbolltem 
object: 

Method Description 

symbol Item, con vertToCompi ledCl ipO Method; converts a symbol item in the library to a compiled 

movie clip. 

symbol I tern, export SWC ( ) Method; exports the symbol to a SWC file. 

symbol Item, export SWF ( ) Method; exports the symbol item to a SWF file specified by 

aURI. 

Property summary for the Symbolltem object 

In addition to the Item object properties, the following properties are available for the 
Symbolltem object: 



Property 




Description 


symbol Item. 


sourceAutoUpdate 


Property; a Boolean value. If true, the item is updated when 
the FLA is published. 


symbol Item. 


sourceFi 1 ePath 


Property; a string that specifies the path for the source FLA 
file in URI format (file:///). 


symbol Item. 


sourceLi braryName 


Property; a string that specifies the name of the item in the 
source file library. 


symbol Item. 


symbol Type 


Property; a string that specifies the type of symbol. 


symbol Item. 


time! ine 


Read-only; a Timeline object. 



symbolltem. convertToCompiledClip() 

Availability 

Flash MX 2004. 
Usage 

symbol Item. con vertToCompi 1 edCl i p( ) 
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Parameters 

None. 
Returns 

Nothing. 
Description 

Method; converts a symbol item in the library to a compiled movie clip. 
Example 

The following example converts an item in the library to a compiled movie clip: 

f 1 . get Document DOM ( ) . 1 i brary . i terns [3] . convertToCompi 1 edCl i p( ) ; 

symbolltem.exportSWC() 

Availability 

Flash MX 2004. 

Usage 

symbol Item. exportSWC( outputURI ) 
Parameters 

The outputURI parameter is a string that specifies the URI for the SWC file to which the method 
will export the symbol. The URI must reference a local file. Flash does not create a folder if the 
specified path does not exist. 

Returns 

Nothing. 
Description 

Method; exports the symbol to a SWC file. 
Example 

The following example exports an item in the library to the SWC file named my.swc in the tests 
folder: 

f 1 . get Document DOM ( ) . 1 i brary . i terns [0] . exports WC( "fi 1 e: ///c | /tests/my . swc" ) ; 

symbolltem.exportSWF() 

Availability 

Flash MX 2004. 
Usage 

symbol Item. exportSWF( outputURI ) 
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Parameters 

The outputURI parameter is a string that specifies the URI for the SWF file to which the method 
will export the symbol. This URI must reference a local file. Flash will not create a folder if the 
specified path doesn't exist. 

Returns 

Nothing. 
Description 

Method; exports the symbol item to a SWF file specified by a URI. 
Example 

The following example exports an item in the library to the my.swf file in the tests folder: 
f 1 . get Document DOM ( ) . 1 i brary . i terns [0] .exportSWF("file:///c|/tests/my.swf"); 

symbolltem.sourceAutoUpdate 

Availability 

Flash MX 2004. 
Usage 

symbol Item. sourceAutoUpdate 
Description 

Property; a Boolean value. If true, the item is updated when the FLA is published. The default 
value is f al se. Used for Shared Library symbols. 

Example 

The following example sets the sourceAutoUpdate property for a library item: 

fl . getDocumentDOM( ). 1 i brary . i terns [0] . sourceAutoUpdate = true; 

symbolltem.sourceFilePath 

Availability 

Flash MX 2004. 
Usage 

symbol Item.sourceFilePath 
Description 

Property; a string that specifies the path for the source FLA file in URI format (file:///). Must be 
an absolute path, not a relative path. Used for Shared Library symbols. 

Example 

The following example shows the value of the sourceFi 1 ePath property in the Output panel: 

fl . trace(f 1 . get Document DOM ( ).li brary. it ems[0].sourceFilePatn); 
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symbolltem.sourceLibraryName 

Availability 

Flash MX 2004. 
Usage 

symbol Item. sourceLi bra ry Name 
Description 

Property; a string that specifies the name of the item in the source file library. Used for Shared 
Library symbols. 

Example 

The following example shows the value of the sourceLi bra ry Name property in the Output 
panel: 

fl . trace(f 1 . get Document DOM ( ) . 1 i bra ry . i terns [0] .sourceLi bra ry Name) ; 
symbolltem.symbolType 

Availability 

Flash MX 2004. 

Usage 

symbol Item.symbolType 

Description 

Property; a string that specifies the type of symbol. Acceptable values are "movi e clip", 
"button", and "graphi c". 

Example 

The following example shows the current value of the symbol Type property, changes it to 
"button", and shows it again: 

al ert ( f 1 . get Document DOM ( ) . 1 i brary . i terns [0] . symbol Type ) ; 

Tl . getDocumentDOMt ). 1 i brary . i terns [0] . symbol Type = "button"; 

al ert ( Tl . get Document DOM ( ) . 1 i brary . i terns [0] . symbol Type ) ; 

symbolltem.timeline 

Availability 

Flash MX 2004. 

Usage 

symbol Item. time 1 i ne 

Description 

Read-only property; a Timeline object. 
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Example 

The following example obtains and shows the number of layers that the selected movie clip in the 
library contains: 

var tl = fl . getDocumentDOM( ). 1 i brary . getSel ectedl terns () [0] . ti mel i ne ; 
al ertttl . 1 ayerCount) ; 
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TextAttrs object 

Availability 

Flash MX 2004. 
Description 

The TextAttrs object contains all the properties of text that can be applied to a subselection. This 
object is a property of the TextRun object (textRun . textAttrs). 

Property summary for the TextAttrs object 

The following properties are available for the TextAttrs object. 



Property 




Description 


textAttrs 


.ali asText 


Property; a Boolean value that specifies that Flash should draw the 
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text. 


textAttrs 


.ali gnment 


Property; a string that specifies paragraph justification. Acceptable 
values are "left", "center", "right", and "justify". 


textAttrs 


. autoKern 


Property; a Boolean value that determines whether Flash uses 
(true) or ignores (f al se) pair kerning information in the font(s) to 
kern the text. 


textAttrs 


.bold 


Property; a Boolean value. A value of true causes text to appear 
with the bold version of the font. 


textAttrs 


. characterPosi ti on 


Property; a string that determines the baseline for the text. 


textAttrs 


.characterSpacing 


Property; an integer that represents the space between characters. 


textAttrs 


. face 


Property; a string that represents the name of the font, such as 

" A r i a 1 


textAttrs 


.fill Col or 


Property; a string that specifies the fill color. 


textAttrs 


, i ndent 


Property; an integer that specifies paragraph indentation. 


textAttrs 


.italic 


Property; a Boolean value. A value of true causes text to appear 
with the italic version of the font. 


textAttrs 


. 1 eftMargi n 


Property; an integer that specifies the paragraph's left margin. 


textAttrs 


. 1 i neSpaci ng 


Property; an integer that specifies the line spacing (leading) of the 
paragraph 


textAttrs 


. rightMargin 


Property; an integer that specifies the paragraph's right margin. 


textAttrs 


. rotati on 


Property; a Boolean value. A value of t rue causes Flash to rotate the 
characters of the text 90S. The default value is f al se. 


textAttrs 


.size 


Property; an integer that specifies the size of the font. 


textAttrs 


.target 


Property; a string that represents the target property of the text 
field. 


textAttrs 


. url 


Property; a string that represents the URL property of the text field. 
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textAttrs.aliasText 

Availability 

Flash MX 2004. 

Usage 

textAttrs . al i as Text 

Description 

Property; a Boolean value that specifies that Flash should draw the text using a method optimized 
for increasing the legibility of small text. 

Example 

The following example sets the al i asText property to true for all the text in the currently 
selected text field: 

f 1 . getDocumentDOM( ) . set El ementTextAttr ( ' al i asText ' , true); 

textAttrs.alignment 

Availability 

Flash MX 2004. 

Usage 

textAttrs . al i gnment 

Description 

Property; a string that specifies paragraph justification. Acceptable values are "1 eft", "center", 
"right", and "justify". 

Example 

The following example sets the paragraphs that contain characters between index 0 up to, but not 
including, index 3 to justify. This can affect characters outside the specified range if they are in 
the same paragraph. 

f 1 . getDocumentDOM( ).setTextSelection(0, 3); 

f 1 . ge t Document DOM ( ) . set El ementTextAttr ( ' al i gnment ' , ' j usti fy ' ) ; 

textAttrs.autoKern 

Availability 

Flash MX 2004. 

Usage 

textAttrs . autoKern 

Description 

Property; a Boolean value that determines whether Flash uses (true) or ignores (f al se) pair 
kerning information in the font(s) to kern the text. 
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This property applies only to static text; it generates a warning if used with other text types. 
Example 

The following example selects the characters from index 2 up to, but not including, index 6 and 
sets the autoKern property to true: 

f 1 . get Document DOM ( ).setTextSelection(3, 6); 

f 1 . getDocumentDOM( ) . set El ementTextAttr ( 'autoKern', true); 

textAttrs.bold 

Availability 

Flash MX 2004. 

Usage 

textAttrs . bol d 

Description 

Property; a Boolean value. A value of t r u e causes text to appear with the bold version of the font. 
Example 

The following example selects the first character of the selected text object and sets the bol d 
property to true: 

f 1 . get Document DOM ( ).setTextSelection(0, 1); 

f 1 . ge t Document DOM ( ) . set El ementTextAttr ( 'bold', true); 

textAttrs.characterPosition 

Availability 

Flash MX 2004. 
Usage 

textAttrs .characterPosition 
Description 

Property; a string that determines the baseline for the text. Acceptable values are "normal ", 
"subscript", and "superscript". This property applies only to static text. 

Example 

The following example selects the characters from index 2 up to, but not including, index 6 of the 
selected text field and sets the characterPosition property to "subscript": 

f 1 . ge t Document DOM ( ).setTextSelection(2, 6); 

f 1 . getDocumentDOM( ) . set El ementTextAttr ( "characterPosition", "subscript"); 
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textAttrs.characterSpacing 

Availability 

Flash MX 2004. 
Usage 

textAttrs .characterSpacing 
Description 

Property; an integer that represents the space between characters. Acceptable values are -60 
through 60. 

This property applies only to static text; it generates a warning if used with other text types. 
Example 

The following example sets the character spacing of the selected text field to 10: 

f 1 . get Document DOM ( ) . set El ementTextAttr ( "characterSpacing", 10); 

textAttrs.face 

Availability 

Flash MX 2004. 

Usage 

textAttrs . face 

Description 

Property; a string that represents the name of the font, such as "Ari al ". 
Example 

The following example sets the font of the selected text field from the character at index 2 up to, 
but not including, the character at index 8 to "Ari al ": 

f 1 . getDocumentD0M( ) . sel ecti on [0] . setTextAttr ( "f ace" , "Arial", 2, 8); 

textAttrs.fillColor 

Availability 

Flash MX 2004. 

Usage 

textAttrs .fill Col or 

Description 

Property; a string that specifies the fill color. The parameter is a color string in hexadecimal 
#rrggbb format (where r is red, g is green, and b is blue), a hexidecimal color value (such as, 
OxffOOOO), or an integer color value. 
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Example 

The following example sets the color of the selected text field from the character at index 2 up to, 
but not including, the character at index 8 to red: 

fl .getDocumentDOM( ) .sel ection[0] . setTextAttr( "f i 1 1 Col or" , OxffOOOO, 2, 8); 

textAttrs.indent 

Availability 

Flash MX 2004. 

Usage 

textAttrs . i ndent 

Description 

Property; an integer that specifies paragraph indentation. Acceptable values are -720 through 720. 
Example 

The following example sets the indentation of the selected text field from the character at index 2 
up to, but not including, the character at index 8 to 100. This can affect characters outside the 
specified range if they are in the same paragraph. 

fl .getDocumentD0M( ) .sel ection[0] . setTextAttr( "i ndent" , 100, 2, 8); 

textAttrs.italic 

Availability 

Flash MX 2004. 

Usage 

textAttrs .italic 

Description 

Property; a Boolean value. A value of t r u e causes text to appear with the italic version of the font. 
Example 

The following example sets the selected text field to italic: 

f 1 . getDocumentD0M( ). select ion[0]. setTextAttr ( "italic", true ) ; 

text Att rs. I ef tMarg i n 

Availability 

Flash MX 2004. 

Usage 

textAttrs .leftMargin 
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Description 

Property; an integer that specifies the paragraphs left margin. Acceptable values are 0 through 
720. 

Example 

The following example sets the leftMargin property of the selected text field from the character 
at index 2 up to, but not including, the character at index 8 to 100. This can affect characters 
outside the specified range if they are in the same paragraph. 

fl .getDocumentDOM( ) .sel ection[0] . setTextAttr( "1 eftMargi n" , 100, 2, 8); 

textAttrs.lineSpacing 

Availability 

Flash MX 2004. 

Usage 

textAttrs . 1 i neSpaci ng 

Description 

Property; an integer that specifies the line spacing {leading) of the paragraph. Acceptable values 
are -360 through 720. 

Example 

The following example sets the selected text field's 1 i neSpaci ng property to 100: 

f 1 . get Document DOM ( ). select i on[0] . setTextAttr ( "lineSpacing", 100); 

textAttrs.rightMargin 

Availability 

Flash MX 2004. 

Usage 

textAttrs .rightMargin 

Description 

Property; an integer that specifies the paragraphs right margin. Acceptable values are 0 through 
720. 

Example 

The following example sets the rightMargin property of the selected text field from the character 
at index 2 up to, but not including, the character at index 8 to 100. This can affect characters 
outside the specified range if they are in the same paragraph. 

fl .getDocumentD0M( ) .sel ection[0] . setTextAttr( "rightMargi n" , 100, 2, 8); 
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textAttrs.rotation 

Availability 

Flash MX 2004. 

Usage 

textAttrs . rotati on 

Description 

Property; a Boolean value. A value of true causes Flash to rotate the characters of the text 90°. 
The default value is false. This property applies only to static text with a vertical orientation; it 
generates a warning if used with other text types. 

Example 

The following example sets the rotation of the selected text field to true: 
f 1 . ge t Document DOM ( ) . set El ementTextAttr ( "rotation", true); 

textAttrs.size 

Availability 

Flash MX 2004. 

Usage 

textAttrs .size 

Description 

Property; an integer that specifies the size of the font. 
Example 

The following example retrieves the size of the character at index 2 and shows the result in the 
Output panel: 

fl .outputPanel . trace ( fl . get Document DOM ( ).selection[0]. getTextAttr ( "size", 2 ) ) ; 

textAttrs.target 

Availability 

Flash MX 2004. 

Usage 

textAttrs .target 

Description 

Property; a string that represents the target property of the text field. This property works only 
with static text. 
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Example 

The following example gets the target property of the text field in the first frame of the top layer 
of the current scene and shows it in the Output panel: 

fl .outputPanel . trace ( fl . get Document DOM ( ) . getTi mel i ne( ) .1 ayers[0] .frames[0] . el e 
ments [0] . getTextAttr ( "target" )) ; 

textAttrs.url 

Availability 

Flash MX 2004. 

Usage 

textAttrs . url 

Description 

Property; a string that represents the URL property of the text field. This property works only with 
static text. 

Example 

The following example sets the URL of the selected text field to http://www.macromedia.com: 

f 1 . ge t Document DOM ( ) . set El ementTextAttr ( "url " , " http : //www .macromedi a . com" ) ; 
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Text object 

Inheritance Element object > Text object 
Availability 

Flash MX 2004. 
Description 

The Text object represents a single text item in a document. All properties of the text pertain to 
the entire text block. 

To set properties of a text run within the text field, see "Property summary for the TextRun 
object" on page 322. To change properties of a selection within a text field, you can use 
document . setEl ementTextAttr ( ) and specify a range of text, or use the current selection. 

To set text properties of the selected text field, use document . set El ement Property ( ). The 
following example assigns the currently selected text field to the variable textVar: 

f 1 . getDocumentDOM( ) . set El ement Property ( " vari abl eName" , "textVa r " ) ; 

Method summary for the Text object 

In addition to the Element object methods, you can use the following methods with the 
Text object: 



Method Description 



text 


.getTextAttrt ) 


Method; retrieves the specified attribute for the text identified by the 
optional startlndex and endlndex parameters. 


text 


. getTextStri ng ( ) 


Method; retrieves the specified range of text. 


text 


. setTextAttr( ) 


Method; sets the specified attribute associated with the text identified by 

startlndex and endlndex. 


text 


. setTextStri ng ( ) 


Method; changes the text string within this text object. 



Property summary for the Text object 

In addition to the Element object properties, the following properties are available for the 
Text object: 

Property Description 

text . accName Property; a string that is equivalent to the Name field in the Accessibility 

panel. 

text . autoExpand Property; a Boolean value that controls the expansion of the bounding 

width for static text fields or the bounding width and height for dynamic 
or input text. 

text .border Property; a Boolean value that controls whether Flash shows (true) or 

hides (fal se) a border around dynamic or input text. 

text .descri pt ion Property; a string that is equivalent to the Description field in the 

Accessibility panel. 
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Property Description 



text 


. embeddedCha racters 


Property; a string that specifies characters to embed. This is equivalent 
to entering text in the Character Options dialog box. 


text 


. embedRanges 


Property; a string that consists of delimited integers that correspond to 
the items that can be selected in the Character Options dialog box. 


text 


. 1 ength 


Read-only; an integer that represents the number of characters in the 
text object. 


text 


. 1 i neType 


Property; a string that sets the line type to "single line", "multiline", 
"multiline no wrap", or "password". 


text 


.maxCharacters 


Property; an integer that specifies the maximum characters the user can 
enter into this text object. 


text 


.on' entati on 


Property; a string that specifies the orientation of the text field. 


text 


. renderAsHTML 


Property; a Boolean value that controls whether Flash draws the text as 
HTML and interprets embedded HTML tags. 


text 


. scrol 1 abl e 


Property; a Boolean value that controls whether the text can (true) or 
cannot (f al se) be scrolled. 


text 


. sel ectabl e 


Property; a Boolean value that controls whether the text can (true) or 
cannot (f al se) be selected. Input text is always selectable. 


text 


. sel ecti onEnd 


Property; a zero-based integer that specifies the offset of the end of a 
text subselection. 


text 


. sel ecti onStart 


Property; a zero-based integer that specifies the offset of the beginning 
of a text subselection. 


text 


. shortcut 


Property; a string that is equivalent to the Shortcut field in the 
Accessibility panel. 


text 


. si 1 ent 
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Property; a Boolean value that specifies whether the object is accessible. 


text 


. tablndex 


Property; an integer that is equivalent to the Tab Index field in the 
Accessibility panel. 


text 


. textRuns 


Read-only; an array of TextRun objects. 


text 


. textType 


Property; a string that specifies the type of text field. Acceptable values 
are "static", "dynami c", and "input". 


text 


. useDevi ceFonts 


Property; a Boolean value. A value of true causes Flash to draw text 
using device fonts. 


text 


. vari abl eName 


Property; a string that contains the contents of the text object. 



text.accName 

Availability 

Flash MX 2004. 

Usage 

text . accName 
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Description 

Property; a string that is equivalent to the Name field in the Accessibility panel. Screen readers 
identify objects by reading the name aloud. This property cannot be used with dynamic text. 

Example 

The following example retrieves the name of the object: 

var theName = 

f 1 . get Document DOM ( ) . getTimel ine( ) .1 ayers[0] . frame s [0] .el ements [0] . accName ; 
The following example sets the name of the currently selected object: 
f 1 . getDocumentDOM( ) . sel ecti on [0] . accName = "Home Button"; 

text.autoExpand 

Availability 

Flash MX 2004. 

Usage 

text . autoExpand 

Description 

Property; a Boolean value. For static text fields, a value of true causes the bounding width to 
expand to show all text. For dynamic or input text fields, a value of true causes the bounding 
width and height to expand to show all text. 

Example 

The following example sets the autoExpand property to a value of true: 
fl . getDocumentD0M( ). sel ecti on[0] . autoExpand = true; 

text. border 

Availability 

Flash MX 2004. 

Usage 

text . border 

Description 

Property; a Boolean value. A value of true causes Flash to show a border around dynamic or 
input text. This property generates a warning if used with static text. 

Example 

The following example sets the border property to a value of true: 

f 1 . get Document DOM ( ). getTimel i ne( ). 1 aye rs [0] . frames [0] . el ements [0] .border = 
true ; 
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text. description 

Availability 

Flash MX 2004. 

Usage 

text . descri pti on 

Description 

Property; a string that is equivalent to the Description field in the Accessibility panel. The 
description is read by the screen reader. 

Example 

The following example retrieves the description of the object: 

var theDescri pti on = 

f 1 . ge t Document DOM ( ) . getTimel i ne( ) . 1 ayersLO] . f ramesLO] . el ements [0] . descri pti 
on ; 

The following example sets the description of the object: 

f 1 . get Document DOM ( ) . getTimel i ne( ) . 1 ayers [0] . f rames [0] . el ements [0] . descri pti on= 
"Enter your name here"; 

text.embeddedCharacters 
Availability 

Flash MX 2004. 
Usage 

text . embeddedCharacters 
Description 

Property; a string that specifies characters to embed. This is equivalent to entering text in the 
Character Options dialog box. 

This property works only with dynamic or input text; it generates a warning if used with other 
text types. 

Example 

The following example sets the embeddedCharacters property to "abc": 
fl . getDocumentD0M( ). sel ecti on[0] . embeddedCharacters = "abc"; 

text.embedRanges 

Availability 

Flash MX 2004. 

Usage 

text . embedRanges 
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Description 

Property; a string that consists of delimited integers that correspond to the items that can be 
selected in the Character Options dialog box. This property works only with dynamic or input 
text; it is ignored if used with static text. 

Note: This property corresponds to the XML file in the Configuration/Font Embedding folder. 
Example 

The following example sets the embed Ranges property to " 1 1 3 | 7 ": 

f 1 . getDocumentDOM( ) .getTimel i net ) .1 ayers [0] . frame s [0] .el ements [0] . embed Ranges 
= " 1 | 3 | 7 " : 

The following example resets the property: 

f 1 . g et Document DOM ( ) .getTimel ine( ) .1 ayers [0] . frame s [0] .el ements [0] . embed Ranges 

text.getTextAttr() 

Availability 

Flash MX 2004. 
Usage 

text . getTextAttr ( a ttrName [, startlndex [, endlndex~\~\) 
Parameters 

att rName A string that specifies the name of the TextAttrs object property to be returned. 

Note: For a list of possible values for att rName, see Property summary for the TextAttrs object. 

startlndex An integer that is the index of first character. This parameter is optional. 

endlndex An integer that specifies the end of the range of text, which starts with s tartlndex 
and goes up to, but does including, endlndex. This parameter is optional. 

Returns 

The value of the attribute specified in the a ttrName parameter. 
Description 

Method; retrieves the attribute specified by the a ttrName parameter for the text identified by the 
optional startlndex and endlndex parameters. If the attribute is not consistent for the specified 
range, Flash returns undef i ned. If you specify startlndex and endlndex, the method uses the 
entire text range. If you specify only startlndex, the range used is a single character at that 
position. If you specify both startlndex and endlndex, the range starts from startlndex and 
goes up to, but not including, endlndex. 

Example 

The following example gets the font size of the currently selected text field and shows it: 

var TheTextSize = fl . getDocumentD0M( ). sel ecti on [0] . getTextAttr (" si ze" ) ; 
fl .trace(TheTextSize) ; 
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The following example gets the text fill color of the selected text field: 

var TheFill = f 1 . getDocumentDOMt ) . sel ecti on [0] . getTextAttr ( "f i 1 1 Col or " ) ; 
fl .tracetTheFil 1 ) ; 

The following example gets the size of the third character: 

var Char2 = fl . getDocumentDOMt ). sel ecti on [0] . getTextAttr (" si ze" , 2); 
fl .trace(Char2) ; 

The following example gets the color of the selected text field from the third through the eighth 
character: 

fl .getDocumentDOMt ) . sel ecti on[0] . getTextAttr ( "f i 1 1 Col or" , 2, 8) ; 

text.getTextString() 

Availability 

Flash MX 2004. 
Usage 

text . getTextStri ng ([ startlndex [, endlndex^ ]) 
Parameters 

startlndex An integer that specifies the index (zero-based) of the first character. This 
parameter is optional. 

endlndex An integer that specifies the end of the range of text, which starts from startlndex 
and goes up to, but not including, endlndex.TWis parameter is optional. 

Returns 

A string of the text in the specified range. 
Description 

Method; retrieves the specified range of text. If you omit the optional parameters startlndex 
and endlndex, the whole text string is returned. If you specify only startlndex, the method 
returns the string starting at the index location and ending at the end of the field. If you specify 
both startlndex and endlndex, the method returns the string starts from startlndex and goes 
up to, but not including, endlndex. 

Example 

The following example gets the character(s) from the fifth character through the end of the 
selected text field: 

var myText = fl . getDocumentDOMt ). sel ecti on [0] . getTextStri ng(4 ) ; 
fl .trace(myText) ; 

The following example gets the fourth through the ninth characters starting in the selected text 
field: 

var myText = fl . getDocumentDOMt ). sel ecti on [0] . getTextStri ng( 3 , 9); 
fl .trace(myText) ; 
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text. length 

Availability 

Flash MX 2004. 

Usage 

text . 1 ength 

Description 

Read-only property; an integer that represents the number of characters in the text object. 
Example 

The following example returns the number of characters in the selected text: 

var textLength = fl . getDocumentDOM( ). sel ecti on [0] . 1 ength ; 

text.lineType 

Availability 

Flash MX 2004. 

Usage 

text . 1 i neType 

Description 

Property; a string that sets the line type. Acceptable values are " s i n g 1 e line", "multiline", 
"multiline no wrap", and "password". 

This property works only with dynamic or input text and generates a warning if used with static 
text. The "password" value works only for input text. 

Example 

The following example sets the 1 i neType property to the value "mul ti line no wrap": 
fl . getDocumentD0M( ). sel ecti on [0] . 1 i neType = "multiline no wrap"; 

text.maxCharacters 

Availability 

Flash MX 2004. 

Usage 

text.maxCharacters 

Description 

Property; an integer that specifies the maximum number of characters the user can enter in this 
text object. 

This property works only with input text; if used with other text types, the property generates a 
warning. 
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Example 

The following example sets the value of the maxCharacters property to 30: 

f 1 . getDocumentDOM( ) . sel ecti on[0] .maxCharacters = 30; 

text. orientation 

Availability 

Flash MX 2004. 

Usage 

text . ori entati on 

Description 

Property; a string that specifies the orientation of the text field. Acceptable values are 
"horizontal ", "vertical left to ri ght", and "verti cal right to left". 

This property works only with static text; it generates a warning if used with other text types. 

Example 

The following example sets the orientation property to " v e r t i c a 1 right to left": 

f 1 . get Document DOM ( ) . getTimel i ne( ) . 1 ayers [0] . f rames [0] . el ements [0] .orientation 
= "vertical right to left"; 

text.renderAsHTML 

Availability 

Flash MX 2004. 

Usage 

text . renderAsHTML 

Description 

Property; a Boolean value. If the value is true, Flash draws the text as HTML and interprets 
embedded HTML tags. 

This property works only with dynamic or input text; it generates a warning if used with other 
text types. 

Example 

The following example sets the renderAsHf ML property to true: 
fl . getDocumentD0M( ). sel ecti on[0] . renderAsHTML = true; 
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text.scrollable 

Availability 

Flash MX 2004. 

Usage 

text . scrol 1 abl e 

Description 

Property; a Boolean value. If the value is true, the text can be scrolled. 

This property works only with dynamic or input text; it generates a warning if used with static 
text. 

Example 

The following example sets the scrollable property to false: 
fl . getDocumentDOMt ). sel ecti on[0] . scrol 1 abl e = false; 

text.selectable 

Availability 

Flash MX 2004. 

Usage 

text . sel ectabl e 

Description 

Property; a Boolean value. If the value is true, the text can be selected. 

Input text is always selectable. It generates a warning when set to false and used with input text. 
Example 

The following example sets the selectable property to true: 

f 1 . getDocumentDOMt ) .getfimel ine( ) .1 ayers[0] . frame s [0] .el ements [0] .selectable = 
true ; 

text.selectionEnd 

Availability 

Flash MX 2004. 

Usage 

text . sel ecti onEnd 

Description 

Property; a zero-based integer that specifies the end of a text subselection. For more information, 

see text . sel ecti onStart. 
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text.selectionStart 



Availability 

Flash MX 2004. 

Usage 

text . sel ecti onStart 

Description 

Property; a zero-based integer that specifies the beginning of a text subselection. You can use this 
property with text .sel ecti onEnd to select a range of characters. Characters up to, but not 
including, text. select ionEnd are selected. 

• If there is an insertion point or no selection, text . sel ecti onEnd is equal to 
text. sel ecti onStart. 

• If text . sel ecti onSta rt is set to a value greater than text. select ionEnd, 
text . sel ecti onEnd is set to text . sel ecti onStart, and no text is selected. 

Example 

The following example sets the start of the text subselection to the sixth character: 

f 1 . get Document DOM ( ) .getTimel ine( ) .1 ayers[0] . frame s [0] .el ements [0] . select ionSta 
rt = 5; 

The following example selects the characters "Barbara" from a text field that contains the text "My 
name is Barbara" and formats them as bold and green: 

fl . getDocumentDOM( ). sel ecti on[0] . sel ecti onStart = 11; 

fl . getDocumentDOM( ). sel ecti on[0] . sel ecti onEnd = 18; 

var s = fl . getDocumentDOM( ). sel ecti on [0] . sel ecti onStart ; 

var e = fl . getDocumentDOMt ). sel ecti on [0] . sel ecti onEnd ; 

f 1 . getDocumentDOMt ) . setEl ementTextAttr( ' bol d ' , true, s, e); 

fl .getDocumentDOMt ) .setEl ementTextAttr( "fi 1 1 Col or" , "#00ff00", s, e); 

text.setTextAttr() 

Availability 

Flash MX 2004. 
Usage 

text . setTextAttr ( a ttrName, attrValue [, startlndex [, endlndex~\~\) 
Parameters 

a ttrName A string that specifies the name of the TextAttrs object property to change. 
attrValue The value for the TextAttrs object property. 

Note: For a list of possible values for attrName and attrValue, see "Property summary for the 
TextAttrs object" on page 299. 

startlndex An integer that is the index (zero-based) of the first character in the array. This 
parameter is optional. 
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endlndex An integer that is a range of text, which starts at sta rtlndex and goes up to, but not 
including, endlndex. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; sets the attribute specified by the a ttrName parameter associated with the text identified 
by startlndex and endlndex to the value specified by attrVa 1 ue. This method can be used to 
change attributes of text that might span TextRun elements (see TextRun object), or that are 
portions of existing TextRun elements. Using it may change the position and number of TextRun 
elements within this object's text . text Runs array. 

If you omit the optional parameters, the method uses the entire text object's character range. If 
you specify only startlndex, the range is a single character at that position. If you specify both 
startlndex and endlndex, the range starts from startlndex and goes up to, but not including, 
the character located at endlndex. 

Example 

The following example sets the selected text field to italic: 

f 1 . getDocumentDOM( ). select ion[0]. setTextAttr ( "italic", true ) ; 

The following example sets the size of the third character to 10: 

f 1 . getDocumentDOMt ) . sel ecti on[0] . setTextAttr( "si ze" , 10, 2); 

The following example sets the color to red for the third through the eighth character of the 
selected text: 

fl .getDocumentDOM( ) .sel ection[0] . setTextAttr( "f i 1 1 Col or" , OxffOOOO, 2, 8); 

text.setTextString() 

Availability 

Flash MX 2004. 
Usage 

text . setTextStri ng ( text [, startlndex [, endlndex~\~\) 
Parameters 

text A string that consists of the characters to be inserted into this text object. 

sta rtlndex An integer that specifies the index (zero-based) of the character in the string where 
the text will be inserted. This parameter is optional. 

endlndex An integer that specifies the index of the end point in the selected text string. The 
new text overwrites the text from startlndex up to, but not including, endlndex. This 
parameter is optional. 

Returns 

Nothing. 
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Description 

Property; changes the text string within this text object. If you omit the optional parameters, the 
whole text object is replaced. If you specify only sta rt Index, the specified string is inserted at the 
startlndex position. If you specify both startlndex and endlndex, the specified string replaces 
the segment of text starting from startlndex up to, but not including, endlndex. 

Example 

The following example assigns the string "this is a stri ng" to the selected text field: 

f 1 . getDocumentDOM( ) . sel ecti on[0] . setTextStri ng( "thi s is a string"); 

The following example inserts the string " a b c " beginning at the fifth character of the selected text 
field: 

fl .get Document DOM ( ) . sel ecti on [0] . setTextStri ng( "01234567890" ) ; 
f 1 . get Document DOM ( ). select i on [0] . setTextStri ng( "a be" , 4 ) ; 
// text field is now "0123abc4567890" 

The following example replaces the text from the third through the eighth character of the 
selected text string with the string " abedef ghi j ". Characters between sta rtlndex and 
endlndex are overwritten. Characters beginning with endlndex follow the inserted string. 

fl .get Document DOM ( ) . sel ecti on [0] . setTextStri ng( "01234567890" ) ; 

f 1 . get Document DOM ( ). select i on[0] . setTextStri ng( "abedef ghi j " , 2 , 8 ) ; 

// text field is now Olabcdefghi j 890 " 

text.shortcut 

Availability 

Flash MX 2004. 

Usage 

text .shortcut 

Description 

Property; a string that is equivalent to the Shortcut field in the Accessibility panel. The shortcut is 
read by the screen reader. This property cannot be used with dynamic text. 

Example 

The following example gets the shortcut key of the selected object and shows the value: 

var theShortcut = fl . getDocumentD0M( ). sel ecti on [0] . shortcut ; 
fl .trace(theShortcut); 

The following example sets the shortcut key of the selected object: 

fl . getDocumentDOMt ). sel ecti on[0] . shortcut = "Ctrl+i"; 
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text.silent 

Availability 

Flash MX 2004. 

Usage 

text . si 1 ent 

Description 

Property; a Boolean value that specifies whether the object is accessible. This is equivalent to the 
inverse logic of the Make Object Accessible setting in the Accessibility panel. That is, if s i 1 ent is 
true, Make Object Accessible is deselected. If it is fal se, Make Object Accessible is selected. 

Example 

The following example determines if the object is accessible (a value of false means that it is 
accessible): 

var isSilent = 

f 1 . ge t Document DOM ( ) . getTimel ine( ) .1 ayers[0] . frame s [0] .el ements [0] .silent; 
The following example sets the object to be accessible: 

f 1 . get Document DOM ( ).getfimeline().layers[0].frames[0].el ements [0] .silent = 
f al se ; 

text.tablndex 

Availability 

Flash MX 2004. 

Usage 

text . tablndex 

Description 

Property; an integer that is equivalent to the Tab Index field in the Accessibility panel. This value 
lets you determine the order in which objects are accessed when the user presses the Tab key. 

Example 

The following example gets the tablndex of the currently selected object: 
var thefablndex = f 1 . getDocumentD0M( ) . sel ecti on [0] . tabl ndex ; 
The following example sets the tablndex of the currently selected object: 
fl . getDocumentDOMt ). sel ecti on[0] . tabl ndex = 1; 
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text.textRuns 

Availability 

Flash MX 2004. 

Usage 

text . textRuns 

Description 

Read-only property; an array of TextRun objects (see TextRun object). 
Example 

The following example stores the value of the textRuns property in the myTextRuns variable: 
var myTextRuns = fl . getDocumentDOM( ). sel ecti on [0] . textRuns ; 

text.textType 

Availability 

Flash MX 2004. 

Usage 

text . textType 

Description 

Property; a string that specifies the type of text field. Acceptable values are "static", "dynamic", 
and "i nput". 

Example 

The following example sets the textType property to "input": 
Tl . getDocumentDOMt ). sel ecti on[0] . textType = "input"; 

text.useDeviceFonts 

Availability 

Flash MX 2004. 

Usage 

text.useDevi ce Fonts 

Description 

Property; a Boolean value. A value of true causes Flash to draw text using device fonts. 
This property works only with static text; it generates a warning if used with other text types. 
Example 

The following example causes Flash to use device fonts with static text. 

Tl . getDocumentDOMt ). sel ecti on[0] . useDevi ceFonts = true; 
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text.variableName 

Availability 

Flash MX 2004. 

Usage 

text . van' abl eName 

Description 

Property; a string that contains the name of the variable associated with the text object. This 
property works only with dynamic or input text; it generates a warning if used with other 
text types. 
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TextRun object 

Availability 

Flash MX 2004. 
Description 

The TextRun object represents a run of characters that have attributes that match all of the 
properties in the TextAttrs object. This object is a property of the Text object (text.textRuns). 

Property summary for the TextRun object 

In addition to the properties available for use with the Text object, the TextRun object provides 
the following properties. 

Property Description 

textRun .characters A string that represents the text contained in the TextRun object. 
textRun . textAttrs The TextAttrs object containing the attributes of the run of text. 

textRun. characters 

Availability 

Flash MX 2004. 

Usage 

textRun . characters 

Description 

Property; the text contained in the TextRun object. 
Example 

The following example displays the characters that make up the first run of characters in the 
selected text field in the Output panel. 

fl . tracetfl . get Document DOM ( ).selection[0]. text Runs[0]. characters); 

textRun.textAttrs 

Availability 

Flash MX 2004. 

Usage 

textRun . textAttrs 

Description 

Property; the TextAttrs object containing the attributes of the run of text. 
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Example 

The following example displays the properties of the first run of characters in the selected text 
field in the Output panel. 

var curTextAttrs = f 1 . getDocumentDOM( ) . sel ecti on [0] . textRuns [0] . textAttrs ; 
for (var prop in curTextAttrs) j 

fl .tracetprop + " = " + curTextAttrs[prop] ) ; 

( 
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Timeline object 

Availability 

Flash MX 2004. 
Description 

The Timeline object represents the Flash Timeline, which can be accessed for the current 
document by f 1 . get Document DOM ( ) . getTi mel i net ). This method returns the Timeline of the 
current scene or symbol that is being edited. 

When you work with scenes, each scene's Timeline has an index value, and can be accessed for the 
current document by f 1 . get Document DOM ( ) . ti mel i nes [ i ]. (In this example, i is the index of 
the value of the Timeline.) 

When you work with frames by using the methods and properties of the Timeline object, 
remember that the frame value is a zero-based index (not the actual frame number in the sequence 
of frames in the Timeline). That is, the first frame has a frame index of 0. 

Method summary for the Timeline object 

The following methods are available for the Timeline object. 
Method Description 

timel ine. addMoti onGui de( ) Adds a motion guide layer above the current layer and 

attaches the current layer to the newly added guide layer. 

timel ine. addNewLayer( ) Adds a new layer to the document and makes it the current 

layer. 

timel i ne . cl ear Frames ( ) Deletes all the contents from a frame or range of frames on 

the current layer. 

timel i ne. cl ear Key f rames( ) Converts a keyframe to a regular frame and deletes its 

contents on the current layer. 

timel i ne . convertToBl ankKeyf rames ( ) Converts frames to blank keyframes on the current layer. 

timel i ne . convertToKeyf rames ( ) Converts a range of frames to keyframes (or converts the 

selection if no frames are specified) on the current layer. 

ti mel i ne . copy Frames ( ) Copies a range of frames on the current layer to the 

Clipboard. 

ti mel i ne . createMoti onTween ( ) Sets the frame . tweenType property to "moti on " for each 

selected keyframe on the current layer, and converts each 
frame's contents to a single symbol instance if necessary. 

timel i ne . cut Frames ( ) Cuts a range of frames on the current layer from the Timeline 

and saves them to the Clipboard. 

timel i ne. del eteLayer( ) Deletes a layer. 

timel i ne . expand Fol der( ) Expands or collapses the specified folder or folders. 

timel ine.fi ndtayerlndex( ) Finds an array of indexes for the layers with the given name. 
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Method 



Description 



timel ine 


getFrameProperty( ) 


Retrieves the specified property's value for the selected 
frames. 


timel ine 


getLayerProperty( ) 


Retrieves the specified property's value for the selected 
layers. 


timel ine 


. getSelectedFramesO 


Retrieves the currently selected frames in an array. 


ti mel i ne 


getSelectedtayersO 


Retrieves the zero-based index values of the currently 
selected layers. 


ti mel i ne 


i nsertBl ankKeyframeC ) 


Inserts a blank keyframe at the specified frame index; if the 
index is not specified, inserts the blank keyframe by using 
the playhead/selection. 


ti mel i ne 


i nsertFrames ( ) 


Inserts the specified number of frames at the given frame 
number. 


ti mel i ne 


i nsertKeyf rame( ) 


Inserts a keyframe at the specified frame. 


timel ine 


pasteFrames ( ) 


Pastes the range of frames from the Clipboard into the 
specified frames. 


timel ine 


. removeFrames ( ) 


Deletes the frame. 


ti mel i ne 


reorderLayer( ) 


Moves the first specified layer before or after the second 
specified layer. 


ti mel i ne 


reverseFrames ( ) 


Reverses a range of frames. 


timel ine 


sel ectAl 1 Frames( ) 


Selects all the frames in the current Timeline. 


timel ine 


setFrameProperty( ) 


Sets the property of the Frame object for the selected 
frames. 


ti mel i ne 


settayerProperty( ) 


Sets the specified property on all the selected layers to a 
specified value. 


ti mel ine 


. setSelected Frames () 


Selects a range of frames in the current layer or sets the 
selected frames to the selection array passed into this 
method. 


ti mel i ne 


. setSelectedLayerst) 


Sets the layer to be selected; also makes the specified layer 
the current layer. 


ti mel i ne 


. showLayerMaski ng( ) 


Shows the layer masking during authoring by locking the 
mask and masked layers. 



Property summary for the Timeline object 

The following methods are available for the Timeline object. 



Property Description 

timel i ne. cur rent Frame A zero-based index for the frame at the current playhead 

location. 

ti mel i ne . current tayer A zero-based index for the currently active layer. 
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Property 



Description 



ti mel i ne . f rameCount 



Read-only; an integer that represents the number of frames 
in this Timeline's longest layer. 



timel ine.l ayerCount 



Read-only; an integer that represents the number of layers in 
the specified Timeline. 



ti mel i ne . 1 ayers 



Read-only; an array of layer objects. 



ti mel i ne . name 



A string that represents the name of the current Timeline. 



timeline. add MotionGuide() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . addMoti onGui de ( ) 
Parameters 

None. 
Returns 

An integer that represents the zero-based index of the newly added guide layer. If the current layer 
type is not of type "Normal", Flash returns -1. 

Description 

Method; adds a motion guide layer above the current layer and attaches the current layer to the 
newly added guide layer, converting the current layer to a layer of type "Guided". 

This method functions only on a layer of type "Normal". It has no effect on a layer whose type is 
"Folder", "Mask", "Masked", "Guide", or "Guided". 

Example 

The following example adds a motion guide layer above the current layer, and converts the 
current layer to "Guided": 

fl . get Document DOM ( ) .getTimel ine( ) .addMotionGuide( ) ; 

timeline.addNewLayer() 

Availability 

Flash MX 2004. 
Usage 

timel i ne . addNewLayer ( [name] [, layerType [, bAddAbove] ] ) 
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Parameters 

name A string that specifies the name for the new layer. If you omit this parameter, a new 
default layer name is assigned to the new layer ("Layer n," where n is the total number of layers). 
This parameter is optional. 

1 ayerType A string that specifies the type of layer to add. If you omit this parameter, a 
"Normal" type layer is created. This parameter is optional. 

bAddAbove A Boolean value that, if set to true (the default), causes Flash to add the new layer 
above the current layer; fal se causes Flash to add the layer below the current layer. This 
parameter is optional. 

Returns 

An integer value of the zero-based index of the newly added layer. 
Description 

Method; adds a new layer to the document and makes it the current layer. 
Example 

The following example adds a new layer to the Timeline with a default name generated by Flash: 

fl . getDocumentDOM( ) .getTimel ine( ) . addNewLayer( ) ; 

The following example adds a new folder layer on top of the current layer and names it 
"Folderl": 

f 1 . get Document DOM ( ) . getTimel i ne ( ) . addNewLayer ( " Fol derl " , "f ol der " , true ) ; 

timeline.clearFrames() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . cl ear Frames ( IstartFramelndex [, endFramelndex]]) 
Parameters 

s tartFramelndex A zero-based index that defines the beginning of the range of frames to clear. 
If you omit startFramelndex, the method uses the current selection. This parameter is optional. 

endFramelndex A zero-based index that defines the end of the range of frames to clear. The 
range goes up to, but does not include, endFramelndex. If you specify only startFramelndex, 
endFramelndex defaults to the value of startFramelndex. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; deletes all the contents from a frame or range of frames on the current layer. 
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Example 

The following example clears the frames from Frame 6 up to, but not including, Frame 1 1 
(remember that index values are different from frame number values) : 

f 1 . ge t Document DOM ( ) .getTimel i ne( ) .cl earFrames(5, 10) ; 

The following example clears Frame 15: 

f 1 . getDocumentDOM( ) .getTimel ine( ) .clearFrames(14) ; 

timeline.clearKeyframes() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . cl earKeyf rames ( IstartFrainelndex [, endFramelndex^^) 
Parameters 

startFramelndex A zero-based index that defines the beginning of the range of frames to clear. 
If you omit sta rtFramelndex, the method uses the current selection. This parameter is optional. 

endFramelndex A zero-based index that defines the end of the range of frames to clear. The 
range goes up to, but does not include, endFramelndex. If you specify only startFramelndex, 
endFramelndex defaults to the value of startFramelndex. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; converts a keyframe to a regular frame and deletes its contents on the current layer. 
Example 

The following example clears the keyframes from Frame 5 up to, but not including, Frame 10 
(remember that index values are different from frame number values) : 

f 1 . getDocumentDOMt ). getTimel i ne (). cl earKeyTrames (4 , 9 ) ; 

The following example clears the keyframe at Frame 1 5 and converts it to a regular frame: 

Tl . getDocumentDOMt ). getTimel i ne (). cl earKeyTrames ( 14 ) ; 

timeline.convertToBlankKeyframes() 

Availability 

Flash MX 2004. 
Usage 

ti me line. convert To Bl ankKeyTrames ( [startFramelndex [ , endFramelndex] ] ) 
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Parameters 

startFramelndex A zero-based index that specifies the starting frame to convert to keyframes. 
If you omit s tartFramelndex, the method converts the currently selected frames. This 
parameter is optional. 

endFramelndex A zero-based index that specifies the frame at which the conversion to 
keyframes will stop. The range of frames to convert goes up to, but does not include, 
endFramelndex. If you specify only startFramelndex, endFramelndex defaults to the value of 
startFramelndex. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; converts frames to blank keyframes on the current layer. 
Example 

The following example converts Frame 2 up to, but not including, Frame 10 to blank keyframes 
(remember that index values are different from frame number values) : 

fl . get Document DOM ( ) .getTimel ine( ) .convertToBl ankKeyf rames ( 1 , 9) ; 

The following example converts Frame 5 to a blank keyframe: 

fl . get Document DOM ( ) .getTimel i net ) .convertToBl ankKeyf rames (4) ; 

timeline.convertToKeyframes() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . con vertTo Key frames ( [startFramelndex [ , endFramelndex] ] ) 
Parameters 

sta rtFramelndex A zero-based index that specifies the first frame to convert to keyframes. If 
you omit sta rtFramelndex, the method converts the currently selected frames. This parameter 
is optional. 

endFramelndex A zero-based index that specifies the frame at which conversion to keyframes 
will stop. The range of frames to convert goes up to, but does not include, endFramelndex. If you 
specify only startFramelndex, endFramelndex defaults to the value of startFramelndex. This 
parameter is optional. 

Returns 

Nothing. 
Description 

Method; converts a range of frames to keyframes (or converts the selection if no frames are 
specified) on the current layer. 
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Example 

The following example converts the selected frames to keyframes: 
fl . get Document DOM ( ) .getTimel ine( ) . con vertTo Key frames ( ) ; 

The following example converts to keyframes the frames from Frame 2 up to, but not including, 
Frame 10 (remember that index values are different from frame number values): 

f 1 . getDocumentDOM( ). getTimel i ne () . convertToKeyf rames ( 1 , 9 ) ; 

The following example converts Frame 5 to a keyframe: 

fl . getDocumentDOM( ) .getTimel i net ) .convertToKeyf rames (4) ; 

timeline.copyFramesO 

Availability 

Flash MX 2004. 
Usage 

timel ine.copyFramest IstartFramelndex [, endFramelndex]]) 
Parameters 

startFramelndex A zero-based index that specifies the beginning of the range of frames to 
copy. If you omit startFramelndex, the method uses the current selection. This parameter is 
optional. 

endFramelndex A zero-based index that specifies the frame at which to stop copying. The 
range of frames to copy goes up to, but does not include, endFramelndex. If you specify only 
startFramelndex, endFramelndex defaults to the value of startFramelndex. This parameter is 
optional. 

Returns 

Nothing. 
Description 

Method; copies a range of frames on the current layer to the Clipboard. 
Example 

The following example copies the selected frames to the Clipboard: 

fl . get Document DOM ( ) .getTimel ine( ) .copyFrames( ) ; 

The following example copies Frame 2 up to, but not including, Frame 10, to the Clipboard 
(remember that index values are different from frame number values): 

f 1 . get Document DOM ( ). getTimel i ne (). copy Frames ( 1 , 9 ) ; 
The following example copies Frame 5 to the Clipboard: 

fl . get Document DOM ( ) .getTimel ine( ) .copy Frames (4) ; 
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timeline.createMotionTween() 

Availability 

Flash MX 2004. 
Usage 

timel i ne . createMoti onTween ( [startFramelndex [ , endFramelndex]] ) 
Parameters 

startFramelndex A zero-based index that specifies the beginning frame at which to create a 
motion tween. If you omit startFramelndex, the method uses the current selection. This 
parameter is optional. 

endFramelndex A zero-based index that specifies the frame at which to stop the motion tween. 
The range of frames goes up to, but does not include, endFramelndex. If you specify only 
startFramelndex, endFramelndex defaults to the startFramelndexvaiue. This parameter is 
optional. 

Returns 

Nothing. 
Description 

Method; sets the frame . tweenType property to "moti on" for each selected keyframe on the 
current layer, and converts each frame's contents to a single symbol instance if necessary. This 
property is the equivalent to the Create Motion Tween menu item in the Flash authoring tool. 

Example 

The following example converts the shape in the first frame up to, but not including, Frame 10 to 
a graphic symbol instance and sets the frame . tweenType to moti on (remember that index values 
are different from frame number values): 

fl . getDocumentDOM( ) .getTimel ine( ) . createMoti onTween ( 0 , 9) ; 

timeline.currentFrame 

Availability 

Flash MX 2004. 

Usage 

timel ine.currentFrame 

Description 

Property; the zero-based index for the frame at the current playhead location. 
Example 

The following example sets the playhead of the current Timeline to Frame 10 (remember that 
index values are different from frame number values): 

fl . getDocumentDOMt ) .getTimel ine( ) . currentFrame = 9; 
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The following example stores the value of the current playhead location in the curFrame variable: 
var curFrame = f 1 . getDocumentDOM( ) . getTi mel i ne( ) . currentFrame ; 

timeline.currentLayer 

Availability 

Flash MX 2004. 

Usage 

timeline.currentLayer 

Description 

Property; the zero-based index for the currently active layer. A value of 0 specifies the top layer, a 
value of 1 specifies the layer below it, and so on. 

Example 

The following example makes the top layer active: 

fl . getDocumentDOM( ) .getTimel ine( ) . currentLayer = 0; 

The following example stores the index of the currently active layer in the curLayer variable: 
var curLayer = fl . getDocumentDOM( ). getTi mel i ne( ). current Layer ; 

timeline.cutFrames() 

Availability 

Flash MX 2004. 
Usage 

timel ine.cutFrames( [startFramelndex [, endFramelndex^^) 
Parameters 

startFramelndex Azero-based index that specifies the beginning of a range of frames to cut. If 
you omit startFramelndex, the method uses the current selection. This parameter is optional. 

endFramelndex A zero-based index that specifies the frame at which to stop cutting. The 
range of frames goes up to, but does not include, endFramelndex. If you specify only 
startFramelndex, endFramelndex defaults to the start Frame Index value. This parameter 
is optional. 

Returns 

Nothing. 

Description 

Method; cuts a range of frames on the current layer from the Timeline and saves them to the 
Clipboard. 
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Example 

The following example cuts the selected frames from the Timeline and saves them to the 
Clipboard: 

fl . get Document DOM ( ) .getTimel ine( ) .cutFrames( ) ; 

The following example cuts Frame 2 up to, but not including, Frame 10 from the Timeline and 
saves them to the Clipboard (remember that index values are different from frame number 
values): 

f 1 . getDocumentDOM( ) .getTimel ine( ) . cut Frames ( 1 , 9) ; 

The following example cuts Frame 5 from the Timeline and saves it to the Clipboard: 

fl . get Document DOM ( ) .getTimel ine( ) .cutFrames(4) ; 

timeline.deleteLayer() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . del ete Layer ( [ index] ) 
Parameters 

index A zero-based index that specifies the layer to be deleted. If there is only one layer in the 
Timeline, this method has no effect. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; deletes a layer. If the layer is a folder, all layers within the folder are deleted. If you do not 
specify the layer index, Flash deletes the currently selected layers. 

Example 

The following example deletes the second layer from the top: 

f 1 . get Document DOM ( ).getTimeline().deleteLayer(l); 
The following example deletes the currently selected layers: 

f 1 . get Document DOM ( ).getTimeline().deleteLayer(); 

timeline.expandFolder() 

Availability 

Flash MX 2004. 
Usage 

timel ine.expandFoldertiFxpand [, bRecurseNestedParents [, /ndex]]) 
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Parameters 

b Expand A Boolean value that, if set to true, causes the method to expand the folder; false 
causes the method to collapse the folder. 

bRecurseNestedParents A Boolean value that, if set to true, causes all the layers within the 
specified folder to be opened or closed, based on the bExpand parameter. This parameter is 
optional. 

index A zero-based index of the folder to expand or collapse. Use -1 to apply to all layers (you 
also must set bRecurseNestedParents to true). This property is equivalent to the Expand AH/ 
Collapse All menu items in the Flash authoring tool. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; expands or collapses the specified folder or folders. If you do not specify a layer, this 
method operates on the current layer. 

Example 

The following examples use this folder structure: 

Folder 1 *** 
- - 1 ayer 7 
--Folder 2 **** 
Layer 5 

The following example expands Folder 1 only: 

fl . getDocumentDOM( ) .getTimel ine( ) . currentLayer = 1; 
f 1 . get Document DOM ( ) . getTi me lineU. expand Folder(true); 

The following example expands Folder 1 only (assuming that Folder 2 collapsed when Folder 1 
last collapsed; otherwise, Folder 2 appears expanded): 

f 1 . ge t Document DOM ( ). getTi me lineU. expand Folder(true, false, 0); 
The following example collapses all folders in the current Timeline: 

f 1 . ge t Document DOM ( ) . getTimel ine(). expand Folder(false, true, -1); 

timeline.findl_ayerlndex() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . fi nd Layer Index ( name) 
Parameters 

name A string that specifies the name of the layer to find. 



334 Chapter 3: Objects 



Returns 

An array of index values for the specified layer. If the specified layer is not found, Flash returns 

undef i ned. 

Description 

Method; finds an array of indexes for the layers with the given name. The layer index is flat, so 
folders are considered part of the main index. 

Example 

The following example shows the index values of all layers named Layer 7 in the Output panel: 

var layerlndex = fl . getDocumentDOM( ). getTi mel i ne( ). fi ndLayerlndext " Layer 7"); 
f 1 .traced ayer Index ) ; 

The following example illustrates how to pass the values returned from this method back to 

timeline.setSelectedLayersU: 

var layerlndex = fl . getDocumentDOM( ). getTi mel i ne( ). fi ndLayerIndex( " Layer 1"); 
f 1 . getDocumentDOM( ) .getTi mel ine( ) .setSel ectedLayersd ayerlndex[0] , true) ; 

timeline.frameCount 

Availability 

Flash MX 2004. 

Usage 

ti mel i ne . f rameCount 

Description 

Read-only property; an integer that represents the number of frames in this Timeline's longest 
layer. 

Example 

The following example uses a countNum variable to store the number of frames in the current 
document's longest layer: 

var countNum = fl . getDocumentDOM( ). getTimel i ne( ). f rameCount ; 

timeline.getFrameProperty() 

Availability 

Flash MX 2004. 

Usage 

timel ine.getFrameProperty(proper£y [, startframelndex [, endFramelndex^^) 
Parameters 

property A string that specifies the name of the property for which to get the value. See 
"Property summary for the Frame object" on page 185 for a complete list of properties. 
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sta rtFramelndex A zero-based index that specifies the starting frame number for which to get 
the value. If you omit sta rtFramelndex, the method uses the current selection. This parameter 
is optional. 

endFramelndex A zero-based index that specifies the end of the range of frames to select. The 
range goes up to, but does not include, endFramelndex. If you specify only startFramelndex, 
endFramelndex defaults to the value of startFramelndex. This parameter is optional. 

Returns 

A value for the specified property, or undef i ned if all the selected frames do not have the same 
property value. 

Description 

Method; retrieves the specified property's value for the selected frames. 
Example 

The following example retrieves the name of the first frame in the current document's top layer 
and displays the name in the Output panel: 

fl . getDocumentDOM( ) .getTimel ine( ) . currentLayer = 0; 

f 1 . get Document DOM ( ). getTi me li net ).setSelectedFrames(0, 0, true); 

var frameName = f 1 . getDocumentDOM( ) . getTi mel i ne( ) . getFrameProperty ( "name" ) ; 

f 1 . tracet frameName ) ; 



timeline.getl_ayerProperty() 

Availability 

Flash MX 2004. 
Usage 

timeline.getLayerProperty( property) 
Parameters 

property A string that specifies the name of the property whose value you want to retrieve. For 
a list of properties, see "Property summary for the Layer object" on page 208. 

Returns 

The value of the specified property. Flash looks at the layer's properties to determine the type. If 
all the specified layers don't have the same property value, Flash returns undefined. 

Description 

Method; retrieves the specified property's value for the selected layers. 
Example 

The following example retrieves the name of the top layer in the current document and displays it 
in the Output panel: 

fl . getDocumentDOMt ) .getTimel ine( ) .currentLayer = 0; 

var layerName = fl . getDocumentD0M( ). getTi mel i ne( ). get LayerProperty ( "name" ) ; 
f 1 . tracet 1 ayerName ) ; 



336 Chapter 3: Objects 



timeline.getSelectedFrames() 

Availability 

Flash MX 2004. 
Parameters 

None. 
Returns 

An array containing 3n integers, where n is the number of selected regions. The first integer in 
each group is the layer index, the second integer is the start frame of the beginning of the 
selection, and the third integer specifies the ending frame of that selection range. The ending 
frame is not included in the selection. 

Description 

Method; retrieves the currently selected frames in an array. 
Example 

With the top layer being the current layer, the following example displays 0,5,10,0,20,25 in the 
Output panel: 

var timeline = f 1 . getDocumentD0M( ) . getTi mel i ne( ) ; 

timeline.setSelectedFrames(5,10); 

timeline.setSelectedFrames(20,25,false); 

var theSel ectedFrames = timel i ne . getSel ectedFrames ( ) ; 

fl .traceCtheSel ectedFrames); 

timeline.getSelectedl_ayers() 

Availability 

Flash MX 2004. 
Parameters 

None. 
Returns 

An array of the zero-based index values of the selected layers. 
Description 

Method; gets the zero-based index values of the currently selected layers. 
Example 

The following example displays 1 , 0 in the Output panel: 

f 1 . ge t Document DOM ( ) . getTi mel ine( ) .setSelectedLayers(O) ; 

f 1 . get Document DOM ( ). getTi me lineU.setSelectedLayersd, False); 

var layerArray = Fl . getDocumentD0M( ). getTi mel i ne( ). getSel ectedLayers () ; 

Fl .traced ayerArray ) ; 
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timeline.insertBlankKeyframe() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . i nsertBl ankKeyf rame ( [ frameNumlndex] ) 
Parameters 

frameNumlndex A zero-based index that specifies the frame at which to insert the keyframe. If 
you omit frameNumlndex, the method uses the current playhead frame number. This parameter 
is optional. 

If the specified or selected frame is a regular frame, the keyframe is inserted at the frame. For 
example, if you have a span of 10 frames numbered 1-10 and you select Frame 5, this method 
makes Frame 5 a blank keyframe, and the length of the frame span is still 10 frames. If Frame 5 is 
selected and is a keyframe with a regular frame next to it, this method inserts a blank keyframe at 
Frame 6. If Frame 5 is a keyframe and the frame next to it is already a keyframe, no keyframe is 
inserted but the playhead moves to Frame 6. 

Returns 

Nothing. 
Description 

Method; inserts a blank keyframe at the specified frame index; if the index is not specified, the 
method inserts the blank keyframe by using the playhead/selection. See also 

ti mel i ne . i nsert Key frame ( ). 

Example 

The following example inserts a blank keyframe at Frame 20 (remember that index values are 
different from frame number values): 

f 1 . ge t Document DOM ( ). getTi mel i net ). i nsertBl ankKeyf rame ( 19 ) ; 

The following example inserts a blank keyframe at the currently selected frame (or playhead 
location if no frame is selected): 

f 1 . get Document DOM ( ) .getTi mel ine( ) .insertBl ankKeyf rame ( ) ; 

timeline.insertFrames() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . i nsert Frames ( [numFrames [, bAllLayers [, frameNumlndex]]]) 
Parameters 

numFrames An integer that specifies the number of frames to insert. If you omit this parameter, 
the method inserts frames at the current selection in the current layer. This parameter is optional. 
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bA 1 1 Layers A Boolean value that, if set to true (the default), causes the method to insert the 
specified number of frames in the numFrames parameter into all layers; if set to f al se, the 
method inserts frames into the current layer. This parameter is optional. 

franieNumlndex A zero-based index that specifies the frame at which to insert a new frame. 
This parameter is optional. 

Returns 

Nothing. 
Description 

Method; inserts the specified number of frames at the specified index. 
If no parameters are specified, this method works as follows: 

• If one or more frames are selected, the method inserts the selected number of frames at the 
location of the first selected frame in the current layer. That is, if frames 6 through 10 are 
selected (a total of five frames), the method adds five frames at Frame 6 on the layer containing 
the selected frames. 

• If no frames are selected, the method inserts one frame at the current frame on all layers. 
If parameters are specified, the method works as follows: 

• If only numFrames is specified, inserts the specified number of frames at the current frame on 
the current layer. 

• If numFrames is specified and bA 1 1 Layers is true, inserts the specified number of frames at 
the current frame on all layers. 

• If all three parameters are specified, inserts the specified number of frames at the specified 
index ( framelndex); the value passed for bA 1 1 Layers determines if the frames are added only 
to the current layer or to all layers. 

If the specified or selected frame is a regular frame, the frame is inserted at that frame. For 
example, if you have a span of 10 frames numbered 1-10 and you select Frame 5 (or pass a 
value of 4 for framelndex), this method adds a frame at Frame 5, and the length of the frame 
span becomes 1 1 frames. If Frame 5 is selected and it is a keyframe, this method inserts a frame at 
Frame 6 regardless of whether the frame next to it is also a keyframe. 

Example 

The following example inserts a frame (or frames, depending on the selection) at the current 
selection in the current layer: 

f 1 . getDocumentDOM( ) .getTimel ine( ) .insertFrames( ) ; 

The following example inserts five frames at the current frame in all layers: 

f 1 . ge t Document DOM ( ) .getTimel ine( ) . i nsertFrames(5) ; 

Note: If you have multiple layers with frames in them, and you select a frame in one layer when using 
the previous command, Flash inserts the frames in the selected layer only. If you have multiple layers 
with no frames selected in them, Flash inserts the frames in all layers. 
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The following example inserts three frames in the current layer only: 

f 1 . getDocumentDOMt ) .getTimel i ne( ) . i nsert Frames (3 , fal se) ; 

The following example inserts four frames in all layers, starting from the first frame: 

fl . getDocumentDOMt ). getTimel i ne (). i nsertFrames (4 , true, 0); 

timeline.insertKeyframe() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . i nsertKeyf rame ( [ frameNumlndex! ) 
Parameters 

frameNumlndex A zero-based index that specifies the frame index at which to insert the 
keyframe in the current layer. If you omit frameNumlndex, the method uses the frame number of 
the current playhead or selected frame. This parameter is optional. 

Returns 

Nothing. 
Description 

Method; inserts a keyframe at the specified frame. If you omit the parameter, the method inserts a 
keyframe using the playhead or selection location. 

This method works the same as timel i ne . i nsertBl ankKeyf rame( ) except that the inserted 
keyframe contains the contents of the frame it converted (that is, it's not blank). 

Example 

The following example inserts a keyframe at the playhead or selected location: 

f 1 . getDocumentDOMt ). getTimel i ne (). i nsert Key Tramet ) ; 

The following example inserts a keyframe at Frame 10 of the second layer (remember that index 
values are different from frame or layer number values): 

Tl .getDocumentDOMt ) .getTimel ine( ) . currentLayer = 1; 
Tl . getDocumentDOMt ). getTimel i ne (). i nsert Key Tramet 9 ) ; 

timeline. layerCount 

Availability 

Flash MX 2004. 

Usage 

ti mel i ne . 1 ayerCount 

Description 

Read-only property; an integer that represents the number of layers in the specified Timeline. 
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Example 

The following example uses the NumLayer variable to store the number of layers in the current 
scene: 

var NumLayer = f 1 . getDocumentDOMt ) . getTimel i ne ( ) . 1 ayerCount ; 

timeline. layers 

Availability 

Flash MX 2004. 

Usage 

ti mel i ne . 1 ayers 

Description 

Read-only property; an array of layer objects. 
Example 

The following example uses the currentLayers variable to store the array of layer objects in the 
current document: 

var currentLayers = fl . getDocumentDOM( ). getTi mel i ne( ). 1 ayers ; 

timeline.name 

Availability 

Flash MX 2004. 

Usage 

ti mel i ne . name 

Description 

Property; a string that specifies the name of the current Timeline. This name is the name of the 
current scene, screen (slide or form), or symbol that is being edited. 

Example 

The following example retrieves the first scene name: 
var sceneName = fl . getDocumentDOM( ). ti mel i nes [0] . name ; 
The following example sets the first scene name to FirstScene: 
fl . getDocumentD0M( ) .timel ines[0] .name = "FirstScene"; 

timeline.pasteFrames() 

Availability 

Flash MX 2004. 

Usage 

timel ine.pasteFrames( [startFramelndex [, endFrameIndex~\~\) 
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Parameters 

startFramelndex A zero-based index that specifies the beginning of a range of frames to paste. 
If you omit startFramelndex, the method uses the current selection. This parameter is optional. 

endFramelndex A zero-based index that specifies the frame at which to stop pasting frames. 
The method pastes up to, but not including, endFramelndex. If you specify only 
startFramelndex, endFramelndex defaults to the start Frame Index value. This parameter 
is optional. 

Returns 

Nothing. 
Description 

Method; pastes the range of frames from the Clipboard into the specified frames. 
Example 

The following example pastes the frames on the Clipboard to the currently selected frame or 
playhead location: 

fl . getDocumentDOM( ) .getTimel ine( ) .pasteFrames( ) ; 

The following example pastes the frames on the Clipboard at Frame 2 up to, but not including, 
Frame 10 (remember that index values are different from frame number values): 

f 1 . get Document DOM ( ). getTimel i ne( ). paste Frames ( 1 , 9); 

The following example pastes the frames on the Clipboard starting at Frame 5: 

fl . get Document DOM ( ).getTimeline().pasteFrames(4); 

timeline. removeFrames() 

Availability 

Flash MX 2004. 
Usage 

timel ine. removeFrames ( [startFramelndex [, endFramelndex]]) 
Parameters 

startFramelndex A zero-based index that specifies the first frame at which to start removing 
frames. If you omit startFramelndex, the method uses the current selection; if there is no 
selection, all frames at the current playhead on all layers are removed. This parameter is optional. 

endFramelndex A zero-based index that specifies the frame at which to stop removing frames; 
the range of frames goes up to, but does not include, endFramelndex. If you specify only 
startFramelndex, endFramelndex defaults to the startFramelndex value. This parameter 
is optional. 

Returns 

Nothing. 
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Description 

Method; deletes the frame. 
Example 

The following example deletes Frame 5 up to, but not including, Frame 10 of the top layer in the 
current scene (remember that index values are different from frame number values): 

fl . getDocumentDOM( ) .getTimel ine( ) . currentLayer = 0; 
f 1 . getDocumentDOM( ). getTimel i ne( ) . remove Frames (4 , 9 ) ; 

The following example deletes Frame 8 on the top layer in the current scene: 

fl . getDocumentDOM( ) .getTimel ine( ) .currentLayer = 0; 
f 1 . getDocumentDOM( ). getTimel i ne () . remove Frames ( 7 ) ; 

timeline.reorderLayerQ 

Availability 

Flash MX 2004. 

Usage 

timel ine. reorderLayer( layerToMove, 1 ayerToPutltBy [, bAddBefore^) 
Parameters 

7 ayerToMove Azero-based index that specifies which layer to move. 

1 ayerToPutltBy A zero-based index that specifies which layer you want to move the layer next 
to. For example, if you specify 1 for 1 ayerToMove and 0 for 1 ayerToPutltBy, the second layer is 
placed next to the first layer. 

bAddBefore Specifies whether to move the layer before or after 1 ayerToPutltBy. If you specify 
fal se, the layer is moved after 7 ayerToPutltBy. The default value is true. This parameter is 
optional. 

Returns 

Nothing. 
Description 

Method; moves the first specified layer before or after the second specified layer. 
Example 

The following example moves the layer at index 2 to the top (on top of the layer at index 0): 

f 1 . get Document DOM ( ) .getTimel ine( ) . reorderLayer(2, 0) ; 

The following example places the layer at index 3 after the layer at index 5: 

fl . getDocumentDOMt ). getTimel i ne (). reorder Layer ( 3 , 5, false); 
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timeline.reverseFrames() 

Availability 

Flash MX 2004. 
Usage 

timel ine. reverseFrames ( [startFramelndex [, endFramelndex^]) 
Parameters 

startFramelndex A zero-based index that specifies the first frame at which to start reversing 
frames. If you omit startFramelndex, the method uses the current selection. This parameter is 
optional. 

endFramelndex A zero-based index that specifies the first frame at which to stop reversing 
frames; the range of frames goes up to, but does not include, endFramelndex. If you specify only 
startFramelndex, endFramelndex defaults to the value of startFramelndex. This parameter is 
optional. 

Returns 

Nothing. 
Description 

Method; reverses a range of frames. 
Example 

The following example reverses the positions of the currently selected frames: 

f 1 . ge t Document DOM ( ) .getTimel ine( ) . reverseFrames( ) ; 

The following example reverses frames from Frame 10 up to, but not including, Frame 15 
(remember that index values are different from frame number values): 

f 1 . get Document DOM ( ) .getTimel ine( ) . reverseFrames(9, 14) ; 

timeline.selectAIIFramesO 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . sel ectAl 1 Frames ( ) 
Parameters 

None. 
Returns 

Nothing. 
Description 

Method; selects all the frames in the current Timeline. 
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Example 

The following example selects all the frames in the current Timeline. 

f 1 . get Document DOM ( ) . getTimel i ne ( ) . sel ectAl 1 Frames ( ) ; 

timeline.setFramePropertyO 

Availability 

Flash MX 2004. 
Usage 

timel ine.setFramePropertytproperty, value [, startFramelndex [, 
endFramelndex] ] ) 

Parameters 

property A string that specifies the name of the property to be modified. For a complete list of 
properties and values, see "Property summary for the Frame object" on page 185. 

Note: You can't use this method to set values for read-only properties such as frame, durati on and 
frame .el ements. 

va 1 ue Specifies the value to which you want to set the property. To determine the appropriate 
values and type, see "Property summary for the Frame object" on page 185. 

startFramelndex A zero-based index that specifies the starting frame number to modify. If 
you omit startFramelndex, the method uses the current selection. This parameter is optional. 

endFramelndex A zero-based index that specifies the first frame at which to stop. The range of 
frames goes up to, but does not include, endFramelndex. If you specify startFramelndex but 
omit endFramelndex, endFramelndex defaults to the value of startFramelndex. This 
parameter is optional. 

Returns 

Nothing. 
Description 

Method; sets the property of the Frame object for the selected frames. 
Example 

The following example assigns the ActionScript stop ( ) command to the first frame of the top 
layer in the current document: 

fl .getDocumentDOMt ) .getTimel ine( ) . currentLayer = 0; 

f 1 . getDocumentDOMt ) .getTimel ine( ) . set Sel ectedFrames(0,0,true) ; 

fl .getDocumentDOMt ) .getTimel ine( ) .set Frame Proper ty( "actionScript" , "stop( ) ; " ) ; 

The following example sets a motion tween from Frame 2 up to, but not including, Frame 5, of 
the current layer (remember that index values are different from frame number values): 

fl .getDocumentDOMt ) .getTimel ine( ) . setFrameProperty ( "tweenType" , "motion" ,1,4); 
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timeline.setl_ayerProperty() 

Availability 

Flash MX 2004. 
Usage 

timel ine.setLayerPropertytproperty, value [, 1 ayersToChange~\) 
Parameters 

property A string that specifies the property to set. For a list of properties, see "Layer object" 
on page 208. 

va 1 ue The value to which you want to set the property. Use the same type of value you would 
use when setting the property on the Layer object. 

7 ayers ToChange A string that identifies which layers should be modified. Acceptable values are 
"selected", "al 1 ", and "others ". The default value is "selected" ifyouomit this parameter. 
This parameter is optional. 

Returns 

Nothing. 
Description 

Method; sets the specified property on all the selected layers to a specified value. 
Example 

The following example makes the selected layer(s) invisible: 

f 1 . getDocumentDOMt ) .getTimel ine( ) .setLayerProperty( "vi si bl e" , fal se) ; 

The following example sets the name of the selected layer(s) to "sel Layer": 

fl .getDocumentDOMt ) .getTimel i net ) .set Layer Property ( "name" , "sel Layer" ) ; 

timeline.setSelectedFrames() 

Availability 

Flash MX 2004. 
Usage 

ti mel i ne . setSel ectedFrames ( startFramelndex, endFramelndex [, 
bRepl aceCurrentSel ecti on] ) 

timel ine.setSel ectedFrames ( select i onL i st [ , bRepl aceCurrentSel ecti on~\ ) 
Parameters 

startFramelndex A zero-based index that specifies the beginning frame to set. 

endFramelndex A zero-based index that specifies the end of the selection; endFramelndex is 
the frame after the last frame in the range to select. 
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bRepl aceCurrentSel ecti on A Boolean value that, if it is set to true, causes the currently 
selected frames to be deselected before the specified frames are selected. The default value is true. 

sel ecti on Li st An array of three integers, as returned by ti mel i ne . getSel ec ted Frames ( ). 
Returns 

Nothing. 
Description 

Method; selects a range of frames in the current layer or sets the selected frames to the selection 
array passed into this method. 

Example 

The following example selects the top layer, Frame 1, up to, but not including, Frame 10; it then 
adds Frame 12 up to, but not including, Frame 15 on the same layer to the current selection 
(remember that index values are different from frame number values) : 

f 1 . get Document DOM ( ) .getTimel ine( ) . set Sel ectedFrames(0, 9) ; 

f 1 . get Document DOM ( ).getTimeline().setSelectedFrames(ll, 14, false); 

The following example first stores the array of selected frames in the savedSelectionList 
variable, and then uses the array later in the code to reselect those frames after a command or user 
interaction has changed the selection: 

var savedSelectionList = 

f 1 . ge t Document DOM ( ) . getTimel ine( ) . get Sel ectedFrames( ) ; 
// do something that changes the selection 

f 1 . get Document DOM ( ) .getTimel ine( ) .setSelectedFrames(savedSelectionList) ; 

The following example selects the top layer, Frame 1, up to, but not including, Frame 10, then 
adds Frame 12, up to, but not including, Frame 15, on the same layer to the current selection: 

f 1 . g et Document DOM ( ).getTimeline().setSelectedFrames([0, 0, 9]); 

fl . getDocumentDOMt ). getTimel i ne (). setSel ectedFrames ( [0 , 11, 14], false); 

timeline.setSelectedLayers() 

Availability 

Flash MX 2004. 
Usage 

timeline.setSelectedLayers( index [ , bRepl aceCurrentSel ecti on} ) 
Parameters 

i ndex A zero-based index for the layer to select. 

bRepl aceCurrentSel ecti on A Boolean value that, if it is set to true, causes the method to 
replace the current selection; false causes the method to extend the current selection. The 
default value is true. This parameter is optional. 

Returns 

Nothing. 
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Description 

Method; sets the layer to be selected, and also makes the specified layer the current layer. Selecting 
a layer also means that all the frames in the layer are selected. 

Example 

The following example selects the top layer: 

f 1 . get Document DOM ( ).getTimeline().setSelectedLayers(0); 
The following example adds the next layer to the selection: 

f 1 . get Document DOM ( KgetTimelineU.setSelectedLayersd, false); 

timeline.showLayerMasking() 

Availability 

Flash MX 2004. 
Usage 

timel ine.showLayerMasking( [ layer] ) 
Parameters 

7 ayer A zero-based index of a mask or masked layer to show masking during authoring. This 
parameter is optional. 

Returns 

Nothing. 
Description 

Method; shows the layer masking during authoring by locking the mask and masked layers. This 
method uses the current layer if no layer is specified. If you use this method on a layer that is not 
of type Mask or Masked, Flash will display an error in the Output panel. 

Example 

The following example specifies that the layer masking of the first layer should show during 
authoring. 

f 1 . get Document DOM ( ) .getTimel ine( ) .show Lay erMaski ng(0) ; 
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ToolObj object 

Availability 

Flash MX 2004. 
Description 

A ToolObj object represents an individual tool in the Tools panel. To access a ToolObj object, use 
properties of the Tools object: either the tool s . tool Obj s array or tool s . acti veTool . 

Method summary for the ToolObj object 

The following methods are available for the ToolObj object. 

Note: The following methods are used only when creating extensible tools. 

Method Description 

tool Obj .enabl ePlControl ( ) Enables or disables the specified control in a PI . Used only when 

creating extensible tools. 

tool Obj . set Icon ( ) Identifies a PNG file to use as a tool icon in the Flash Tools panel. 

tool Obj . setMenuStri ng( ) Sets the string that appears in the pop-up menu as the name for 

the tool. 

tool Obj . setOpti onsFi 1 e( ) Associates an XML file (located in the Configuration/Tools 

folder) with the tool to appear in a modal panel that is invoked by 
an Options button in the Property inspector. 

tool Obj . set PI ( ) Sets a particular Property inspector to be used when the tool is 

activated. 

tool Obj . setTool Name( ) Assigns a name to the tool for the configuration of the Tools 

panel. 

tool Obj . setTool Ti p( ) Sets the tooltip that appears when the mouse is held over the 

tool icon. 

tool Obj . showPlControl ( ) Shows or hides a control in the Property inspector. 

tool Obj . showTransformHandl es ( ) Called in the conf i gureTool ( ) method of an extensible tool's 

JavaScript file to indicate that the free transform handles should 
appear when the tool is active. 

Property summary for the ToolObj object 

The following property is available for the Tools object. 



Property 


Description 


tool Obj . posi ti on 


Read-only; an integer specifying the position of the tool in the 




Tools panel. 
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toolObj.enablePIControlO 

Availability 

Flash MX 2004. 
Usage 

tool Obj . enabl ePIControl ( control, bEnable ) 
Parameters 

contro 1 A string that specifies the name of the control to enable or disable. Legal values 
depend on the Property inspector invoked by this tool (see toolObj .setPK )). 

A shape Property inspector has the following controls: 
stroke fill 

A text Property inspector has the following controls: 



type 


font 


pointsize 


color 


bold 


italic 


direction 


alignLeft 


alignCenter 


alignRight 


alignJustify 


spacing 


position 


autoKern 


small 


rotation 


format 


lineType 


selectable 


html 


border 


deviceFonts 


varEdit 


options 


link 


maxChars 


target 


A movie Property inspector has the following 


; controls: 


size 


publish 


background 


framerate 


player 


profile 



bEnab 1 e A Boolean value that determines whether to enable (true) or disable (false) the 
control. 

Returns 

Nothing. 
Description 

Method; enables or disables the specified control in a PI . Used only when creating extensible 
tools. 
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Example 

The following command in an extensible tool's JavaScript file will set Flash to not show the stroke 
options in the Property inspector for that tool: 

theTool . enabl ePIControl ( "stroke", false); 

toolObj. position 

Availability 

Flash MX 2004. 

Usage 

tool Ob j . posi ti on 

Description 

Read-only property; an integer specifying the position of the tool in the Tools panel. 
Example 

The following commands in the mouseDown ( ) method of a tool's JavaScript file will show that 
tool's position in the Tools panel as an integer in the Output panel: 

myToolPos = fl . tool s . acti veTool . posi ti on ; 
f 1 . traceCmyTool Pos ) ; 

toolObj.setlcon() 

Availability 

Flash MX 2004. 
Usage 

tool Obj . set Icon ( file ) 
Parameters 

file A string that specifies the name of the PNG file to use as the icon. The PNG file must be 
placed in the Configuration/Tools folder. 

Returns 

Nothing. 
Description 

Method; identifies a PNG file to use as a tool icon in the Flash Tools panel. 
Example 

The following example specifies that the image in the arrowl.png file should be used as the icon 
for the tool named theTool . 

theTool .set!con("arrowl.png"); 
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toolObj.setMenuString() 

Availability 

Flash MX 2004. 
Usage 

tool Obj . setMenuStri ng ( menuStr ) 
Parameters 

menuStr A string that specifies the name that appears in the pop-up menu as the name for the 
tool. 

Returns 

Nothing. 
Description 

Method; sets the string that appears in the pop-up menu as the name for the tool. 
Example 

The following example specifies that the tool named theTool should display the name 
"Arrow Style 1 " in its pop-up menu. 

theTool . setMenuStri ng ( "Arrow Style 1"); 

toolObj.setOptionsFile() 

Availability 

Flash MX 2004. 
Usage 

tool Obj . setOpti ons Fi 1 e ( xmlFile ) 
Parameters 

xml File A string that specifies the name of the XML file that has the description of the tool's 
options. 

Returns 

Nothing. 
Description 

Method; associates an XML file (located in the Configuration/Tools folder) with the tool to 
appear in a modal panel that is invoked by an Options button in the Property inspector. 

Example 

The following example specifies that the file named myTool.xml is associated with the currently 
active tool. You would usually use code like this in the configureTool ( ) method. 

fl . tool s . acti veTool . setOpti ons Fi 1 e( "myTool.xml" ); 
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toolObj.setPIO 

Availability 

Flash MX 2004. 

Usage 

toolObj .setPK pi ) 

Parameters 

p 7 A string that specifies the Property inspector to invoke for this tool. 
Returns 

Nothing. 
Description 

Method; specifies which Property inspector should be used when the tool is activated. Valid 
values are "shape" (the default), "text", and "movie". 

Example 

The following example specifies that the text Property inspector should be used when the tool is 
activated. 

f 1 . tool s . acti veTool . setPI ( "text" ); 

toolObj.setToolName() 

Availability 

Flash MX 2004. 
Usage 

tool Obj . setTool Name ( name ) 
Parameters 

name A string that specifies the name of the tool. 
Returns 

Nothing. 
Description 

Method; assigns a name to the tool for the configuration of the Tools panel. The name is used 
only by the XML layout file that Flash reads to construct the Tools panel. The name does not 
show up in the Flash user interface. 

Example 

The following example assigns the name "arrowl" to the tool named theTool . 
theTool . setTool Name ( "arrowl " ) ; 
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toolObj.setToolTip() 

Availability 

Flash MX 2004. 
Usage 

tool Obj . setTool Ti p( toolTip ) 
Parameters 

too 1 Ti p A string that specifies the tooltip to use for the tool. 
Returns 

Nothing. 
Description 

Method; sets the tooltip that appears when the mouse is held over the tool icon. 
Example 

The following example specifies that the tooltip for the tool should be "Arrow Style 1 Tool." 

fl . tool s . acti veTool . setTool Ti p( "Arrow Style 1 Tool"); 

toolObj.showPIControlO 

Availability 

Flash MX 2004. 
Usage 

tool Obj . showPIControl ( control, bShow ) 
Parameters 

contro 1 A string that specifies the name of the control to show or hide. Valid values depend on 
the Property Inspector invoked by this tool (see tool Obj . setPI ( )). 

A shape Property inspector has the following controls: 
stroke fill 

A text Property inspector has the following controls: 



type 

color 

direction 

alignRight 

position 

rotation 

selectable 



font 
bold 

alignLeft 

alignJustify 

autoKern 

format 

html 



pointsize 
italic 

alignCenter 

spacing 

small 

lineType 

border 
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deviceFonts varEdit options 

link maxChars target 

The movie Property inspector has the following controls: 

size publish background 

framerate player profile 

bShow A Boolean value that determines whether to show or hide the specified control (true 
shows the control; f al se hides the control). 

Returns 

Nothing. 
Description 

Method; shows or hides a control in the Property inspector. 
Example 

The following command in an extensible tool's JavaScript file will set Flash to not show the fill 
options in the Property inspector for that tool: 

f 1 . tool s . acti veTool . showPIControl ( "fill", false ); 

toolObj.showTransformHandles() 

Availability 

Flash MX 2004. 
Usage 

tool Obj . showf ransf ormHandl es ( bShou ) 
Parameters 

bShow A Boolean value that determines whether to show or hide the free transform handles for 
the current tool (true shows the handles; fal se hides them). 

Returns 

Nothing. 
Description 

Method; called in the conf i gureTool ( ) method of an extensible tool's JavaScript file to indicate 
that the free transform handles should appear when the tool is active. 

Example 

See conf i gureTool ( ). 
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Tools object 

Availability 

Flash MX 2004. 
Description 

The Tools object is accessible from the Flash object (f 1 . tool s). The tool s . tool Objs property 
contains an array of ToolObj objects, and the tool s . acti veTool property returns the ToolObj 
object for the currently active tool. (See also ToolObj object.) 

Note: The following methods and properties are used only when creating extensible tools. 

Method summary for the Tools object 

The following methods are available for the Tools object. 



Method Description 



tool s 


. constrai nPoi nt ( ) 


Takes two points and returns a new adjusted or constrained point. 


tool s 


, getKeyDown ( ) 


Returns the most recently pressed key. 


tool s 


. setCursor( ) 


Sets the pointer to a specified appearance. 


tool s 


, snapPoi nt( ) 


Takes a point as input and returns a new point that may be adjusted or 






snapped to the nearest geometric object. 



Property summary for the Tools object 

The following properties are available for the Tools object. 



Property Description 



tool s 


.acti veTool 


Read-only; returns the ToolObj object for the currently active tool. 


tool s 


. al tlsDown 


Read-only; a Boolean value that identifies if the Alt key is being pressed. 


tool s 


. ctl IsDown 


Read-only; a Boolean value that identifies if the Control key is being 
pressed. 


tool s 


.mouselsDown 


Read-only; a Boolean value that identifies if a mouse button is currently 
pressed. 


tool s 


. penDowntoc 


Read-only; a point that represents the position of the last mouse-down 
event on the Stage. 


tool s 


. pentoc 


Read-only; a point that represents the current location of the mouse. 


tool s 


. shi ftlsDown 


Read-only; a Boolean value that identifies if the Shift key is being pressed. 


tool s 


, tool Objs 


Read-only; an array of ToolObj objects. 
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tools.activeTool 

Availability 

Flash MX 2004. 

Usage 

tool s . acti veTool 

Description 

Read-only property; returns the ToolObj object for the currently active tool. 
Example 

The following example saves an object that represents the currently active tool in the theTool 
variable. 

var theTool = fl . tool s . acti veTool ; 

tools.altlsDown 

Availability 

Flash MX 2004. 

Usage 

tool s . al tlsDown 

Description 

Read-only property; a Boolean value that identifies if the Alt key is being pressed. The value is 
true if the Alt key is pressed, and false otherwise. 

tools.constrainPoint() 

Availability 

Flash MX 2004. 
Usage 

tool s.constrainPointtpti, ptZ) 
Parameters 

ptl and ptZ specify the starting-click point and the drag-to point. 
Description 

Method; takes two points and returns a new adjusted or constrained point. If the Shift key is 
pressed, then the returned point is constrained to follow either a 45° constrain (useful for 
something such as a line with an arrowhead) or to constrain an object to maintain its aspect ratio 
(such as pulling out a perfect square with the rectangle tool). 
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tools. ctllsDown 

Availability 

Flash MX 2004. 

Usage 

tool s . ctl IsDown 

Description 

Read-only property; a Boolean value that identifies if the Control key is being pressed. The value 
is true if the Control key is pressed, and f al se otherwise. 

tools.getKeyDown() 

Availability 

Flash MX 2004. 

Usage 

tool s . getKeyDown( ) 

Parameters 

None. 
Returns 

The integer value of the key. 
Description 

Method; returns the most recently pressed key. 

tools. mouselsDown 

Availability 

Flash MX 2004. 

Usage 

tool s. mouselsDown 

Description 

Read-only property; a Boolean value that identifies if a mouse button is currently pressed. The 
value is true if the left mouse button is currently down, and f al se if the mouse button is up. 

tools. penDownLoc 

Availability 

Flash MX 2004. 

Usage 

tool s . penDown Loc 
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Description 



Read-only property; a point that represents the position of the last mouse-down event on the 
Stage. penDownLoc has two properties, x and y, corresponding to the x,y location of the mouse 
on the current document. 

tools.penLoc 

Availability 

Flash MX 2004. 

Usage 

tool s . penLoc 

Description 

Read-only property; a point that represents the current location of the mouse, pen Loc has two 
properties: x and y, corresponding to the x,y location of the mouse on the current document. 

tools.setCursorQ 

Availability 

Flash MX 2004. 
Usage 

tool s . setCursor ( cursor ) 
Parameters 

cursor An integer that defines the pointer appearance, as described in the following list: 



0 


Plus cursor (+) 


1 


black arrow 


2 


white arrow 


3 


four-way arrow 


4 


two-way horizontal arrow 


5 


two-way vertical arrow 


6 


X 


7 


hand cursor 



Returns 

Nothing. 
Description 

Method; sets the pointer to a specified appearance. 
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Example 

The following example sets the pointer to a black arrow. 

f 1 . tool s . setCursor ( 1 ) ; 

tools.shiftlsDown 

Availability 

Flash MX 2004. 

Usage 

tool s . shi f tlsDown 

Description 

Read-only property; a Boolean value that identifies if the Shift key is being pressed. The value is 
true if the Shift key is pressed, and false otherwise. 

tools.snapPoint() 

Availability 

Flash MX 2004. 

Usage 

tool s.snapPoint(pt) 

Parameters 

p t specifies the location of the point for which you want to return a snap point. 
Description 

Method; takes a point as input and returns a new point that may be adjusted or snapped to the 
nearest geometric object. If snapping is turned off in the View menu in the Flash user interface, 
the point returned is the original point. 

tools. toolObjs 

Availability 

Flash MX 2004. 

Usage 

tool s . tool Objs 

Description 

Read-only property; an array of ToolObj objects (see ToolObj object). 
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Vertex object 

Availability 

Flash MX 2004. 
Description 

The Vertex object is the part of the shape data structure that holds the coordinate data. 

Method summary for the Vertex object 

You can use the following methods with the Vertex object. 
Method Description 

vertex. getHal f Edge( ) Gets a HalfEdge object that shares this vertex, 

vertex. setLocati on ( ) Sets the location of the vertex. 

Property summary for the Vertex object 

The following properties are available for the Vertex object: 

Property Description 

vertex, x Read-only; the x location of the vertex in pixels, 

vert ex. y Read-only; they location of the vertex in pixels. 

vertex.getHalfEdge() 

Availability 

Flash MX 2004. 

Usage 

vertex. getHal f Ed ge() 

Parameters 

None. 
Returns 

A HalfEdge object. 
Description 

Method; gets a HalfEdge object that shares this vertex. 

vertex.setLocation() 

Availability 

Flash MX 2004. 
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Usage 

vertex. setLocationt x, y ) 
Parameters 

x A floating point value that specifies the x coordinate of where the vertex should be positioned, 
in pixels. 

y A floating point value that specifies the y coordinate of where the vertex should be positioned, 
in pixels. 

Returns 

Nothing. 
Description 

Method; sets the location of the vertex. You must call shape . begi nEdi t( ) before using this 
method. 

Example 

The following example sets the vertex to the origin point. 

var shape = f 1 . getDocumentDOMt ) . sel ecti on [0] ; 
var hEdge = shape. edges[0] .getHal fEdge(O) ; 
var vertex = hEdge . getVertext ) ; 

// move the vertex to the origin 
vertex. setLocation(0.0, 0.0); 

vertex.x 

Availability 

Flash MX 2004. 

Usage 

vertex . x 

Description 

Read-only property; the x location of the vertex in pixels. 
Example 

The following example displays the location of the x and y values of the vertex in the Output 
panel. 

var shape = fl . getDocumentDOMt ). sel ecti on [0] ; 
var hEdge = shape. edges[0] .getHal fEdge(O) ; 
var vertex = hEdge . getVertex( ) ; 

fl.tracet'x location of vertex is: ' + vertex.x); 
fl.tracet'y location of vertex is: ' + vertex. y); 
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vertex.y 

Availability 

Flash MX 2004. 

Usage 

vertex.y 

Description 

Read-only property; the y location of the vertex in pixels. 
Example 

See vertex . x. 
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Videoltem object 

Inheritance Item object > Videoltem object 
Availability 

Flash MX 2004. 
Description 

The Videoltem object is a subclass of the Item object. There are no unique methods or properties 
of Videoltem. 
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XMLUI object 



Availability 

Flash MX 2004. 
Description 

Flash MX 2004 supports custom dialog boxes written in a subset of the XML User Interface 
Language (XUL). For more information, see Appendix B, "XML to UI" in Using Flash. You can 
write a dialog.xml file and invoke it from the JavaScript API using the document . xml Panel ( ) 
method. 

An XML User Interface (XMLUI) dialog box can be used by several Flash MX 2004 features, 
such as Commands and Behaviors, to provide a user interface for features that you build using 
extensibility. 

The XMLUI object provides the ability to get and set properties of an XMLUI dialog box, and 
accept or cancel out of one. The XMLUI methods can be used in callbacks, such as oncommand 
handlers in buttons. 

Method summary for the XMLUI object 

The following methods are available for the XMLUI object: 



Method Description 



xml ui 


. acceptt ) 


Method; makes the current XMLUI dialog box exit with an accept state, which is 
equivalent to the user clicking the OK button. 


xml ui 


. cancel ( ) 


Method; makes the current XMLUI dialog box exit with a cancel state, which is 
equivalent to the user clicking the Cancel button. 


xml ui 


.get() 


Method; retrieves the value of the specified property of the current XMLUI 
dialog box. 


xm 1 u i 


.sett ) 


Method; modifies the value of the specified property of the current XMLUI 
dialog box. 



xmlui.accept() 

Availability 

Flash MX 2004. 

Usage 

xml ui . accept ( ) 

Parameters 

None. 
Returns 

Nothing. 
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Description 

Method; makes the current XMLUI dialog box exit with an accept state, which is equivalent to 
the user clicking the OK button. 

xmlui.cancel() 

Availability 

Flash MX 2004. 

Usage 

xml ui . cancel ( ) 

Parameters 

None. 
Returns 

Nothing. 
Description 

Method; makes the current XMLUI dialog box exit with a cancel state, which is equivalent to the 
user clicking the Cancel button. 

xmlui.get() 

Availability 

Flash MX 2004. 

Usage 

xml ui . get (name ) 

Parameters 

name A string that specifies the name of the XMLUI property to retrieve. 
Returns 

A string value for the specified property. In cases where you might expect a Boolean value of t r u e 
or f al se, it returns the string "true" or "f a 1 se". 

Description 

Method; retrieves the value of the specified property of the current XMLUI dialog box. 

xmlui.set() 

Availability 

Flash MX 2004. 
Usage 

xml ui .sett name , value) 
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Parameters 

name A string that specifies the name of XMLUI property to modify. 

val ue A string that specifies the value to which you want to set the XMLUI property. 
Returns 

Nothing. 
Description 

Method; modifies the value of the specified property of the current XMLUI dialog box. 
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CHAPTER 4 

C-Level Extensibility 



The C-level extensibility mechanism lets you implement Macromedia Flash MX 2004 and 
Macromedia Flash Professional MX 2004 extensibility files using a combination of JavaScript and 
custom C code. You define functions using C, bundle them in a dynamic linked library (DLL) or 
a shared library, save the library in the appropriate directory, and then call the functions from 
JavaScript using the Flash JavaScript API (JSAPI). 

For example, you might want to define a function that performs intense calculations more 
efficiently than JavaScript does, which improves performance, or when you want to create more 
advanced tools or effects. 

This extensibility mechanism is essentially a subset of the Macromedia Dreamweaver MX 2004 
API. If you are familiar with that API, you might recognize the functions in this API. However, 
this API differs from the Dreamweaver API in the following ways: 

• This API does not contain all the commands in the Dreamweaver API. 

• All declarations of type wchar_t and char in the Dreamweaver API are implemented as 
unsi gned short declarations in this API, to support Unicode when strings are passed. 

• The JSVal JS_By tesToVal ue( ) function in this API is not part of the Dreamweaver API. 

• The location where DLL or shared library files must be stored is different (see "How 
integrating C functions works" on page 369). 

How integrating C functions works 

The C-level extensibility mechanism lets you implement Flash extensibility files using a 
combination of JavaScript and C code. The process for implementing this capability is 
summarized in the following steps: 

1. Define functions using the C or C++ language. 

2. Bundle them in a DLL file (Windows) or a shared library (Macintosh). 

3. Saves the DLL file or library in the appropriate location: 

■ Windows 2000 or Windows XP: 

C:\Documents and Settings\<user>\Local Settings\ Application Data\Macromedia\ 
Flash MX2004\<language>\Configuration\Templates\External Libraries 
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■ Windows 98: 

C:\Windows\Application Data\Macromedia\Flash MX 2004\ <language>\ 
Configuration\Templates\External Libraries 

■ Macintosh OS X: 

Hard Drive/Users/ <userName>/Library/ Application Support/Macromedia/ 
Flash MX 2004/<language>/Configuration/Templates/External Libraries 

4. Create a JSFL file that calls the functions. 

5. Run the JSFL file from the Commands menu in the Flash authoring environment. 
For more information, see "Sample implementation" on page 374. 

C-level extensibility and the JavaScript interpreter 

The C code in the DLL or shared library interacts with the Flash JSAPI at three different times: 

• At startup, to register the library's functions 

• When the C function is called, to unpack the arguments that are being passed from JavaScript 
to C 

• Before the C function returns, to package the return value 

To accomplish these tasks, the interpreter defines several data types and exposes an API. 
Definitions for the data types and functions that are listed in this section appear in the 
mmjsapi.h file. For your library to work properly, you must include the mm_jsapi.h file at the 
top of each file in your library, with the following line: 

#in elude "mm_jsapi.h" 

Including the mm_jsapi.h file includes the mm_jsapi_environment.h file, which defines the 
MM_Environment structure. 

To get a copy of the mm_jsapi.h file, download the sample ZIP or SIT file (see "Sample 
implementation" on page 374), or copy the following code into a file that you name mm_jsapi.h: 

#ifndef _MM_JSAPI_H_ 
#define _MM_JSAPI_H_ 

/***************************************************************************** 
* Public data types 

********************************************************** 

typedef struct JSContext JSContext; 
typedef struct JSObject JSObject; 
typedef 1 ong jsval ; 
#ifndef JSBool 
typedef 1 ong JSBool ; 
#endi f 

typedef JSBool (*JSNative) (JSContext *cx, JSObject *obj , unsigned int argc, 
jsval *argv, jsval *rval); 

/* Possible values for JSBool */ 
#define JS_fRUE 1 
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#define JS_FALSE 0 



* Public functions 

/* JSBool JS_DefineFunction(unsigned short *name, JSNative call, unsigned int 
nargs) */ 

#define JS_DefineFunction(n, c, a) \ 

(mmEnv.defineFunction ? ( *(mmEnv . defi neFuncti on )) (mmEnv . 1 i bObj , n, c, a) \ 
: JS_FALSE) 

/* unsigned short *JS_Val ueToStri ng( JSContext *cx, jsval v, unsigned int 

*pLength) */ 
^define JS_Val ueToStri ng ( c , v, 1) \ 

(mmEnv . val ueToStri ng ? ( *(mmEnv . val ueToStri ng ))( c , v, 1) : (unsigned short 

*)0) 

/* unsigned char *JS_Val ueToBytes( JSContext *cx, jsval v, unsigned int 

*pLength) */ 
#define JS_Val ueToBytes ( c , v, 1) \ 

(mmEnv . val ueToBytes ? ( *(mmEnv . val ueToBytes ) ) ( c , v, 1) : (unsigned char 

*)0) 

/* JSBool JS_Val ueToInteger( JSContext *cx, jsval v, long *lp); */ 
#define JS_Val ueToInteger ( c , v, 1) \ 

(mmEnv . val ueToInteger ? ( *(mmEnv . val ueToI nteger ) ) ( c , v, 1) : JS_FALSE) 

/* JSBool JS_ValueToDouble(JSContext *cx, jsval v, double *dp); */ 
#define JS_Val ueToDoubl e ( c , v, d) \ 

(mmEnv . val ueToDoubl e ? ( *(mmEnv . val ueToDoubl e ))( c , v, d) : JS_FALSE) 

/* JSBool JS_ValueToBoolean(JSContext *cx, jsval v, JSBool *bp); */ 
#define JS_Val ueToBool ean ( c , v, b) \ 

(mmEnv . val ueToBool ean ? ( *(mmEnv . val ueToBool ean ))( c , v, b) : JS_FALSE) 

/* JSBool JS_ValueToObject(JSContext *cx, jsval v, JSObject **op); */ 
#define JS_Val ueToObject ( c , v, o) \ 

(mmEnv . val ueToObject ? ( *(mmEnv . val ueToObject ))( c , v, o) : JS_FALSE) 

/* JSBool JS_Stri ngToVal ue ( JSContext *cx, unsigned short *bytes, uint sz, 

jsval *vp); */ 
#define JS_Stri ngToVal ue ( c , b, s, v) \ 

(mmEnv . stri ngToVal ue ? ( *(mmEnv . stri ngToVal ue ))( c , b, s, v) : JS_FALSE) 

/* JSBool JS_BytesToVal ue( JSContext *cx, unsigned char *bytes, uint sz, jsval 
*vp); */ 

#define JS_BytesToVal ue ( c , b, s, v) \ 

(mmEnv . bytesToVal ue ? ( *(mmEnv . bytesToVal ue ) ) ( c , b, s, v) : JS_FALSE) 

/* JSBool JS_Doubl eToVal ue( JSContext *cx, double dv, jsval *vp); */ 
#define JS_Doubl eToVal ue ( c , d, v) \ 

(mmEnv . doubl eToVal ue ? ( *(mmEnv . doubl eToVal ue ) ) ( c , d, v) : JS_FALSE) 
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/* jsval JS_IntegerToVal ue( 1 ong Iv); */ 

#define JS_IntegerToVal ue ( 1 v ) ( ( ( j sval ) ( 1 v ) << 1) | 0x1) 

/* jsval JS_Bool eanToVal ue( JSBool bv); */ 

#define JS_Bool eanToVal ue ( bv ) ( ( ( j sval ) ( bv ) << 3) | 0x6) 

/* jsval JS_ObjectToValue(JSObject *obj); */ 
#define JS_ObjectToVal ue ( ov ) ( ( j sval ) ( ov ) ) 

/* unsigned short *JS_ObjectType( JSObject *obj); */ 
#define JS_ObjectType(o) \ 

(mmEnv . objectType ? (*(mmEnv .objectType) ) (o) : (unsigned short *)0) 

/* JSObject *JS_NewArrayObject( JSContext *cx, unsigned int length, jsval *v) 
*/ 

#define JS_NewArrayObject(c, 1, v) \ 

(mmEnv . newArrayObject ? ( *(mmEnv . newArrayObject ) ) ( c , 1, v) : (JSObject *)0) 

/* long JS_GetArrayLength( JSContext *cx, JSObject *obj) */ 
#define JS_GetArrayLength(c, o) \ 

(mmEnv . getArray Length ? ( *(mmEnv . getArray Length ))( c , o) : -1) 

/* JSBool JS_GetEl ement ( JSContext *cx, JSObject *obj , jsint idx, jsval *vp) */ 
#define JS_GetEl ement ( c , o, i, v) \ 

(mmEnv . getEl ement ? ( *(mmEnv . getEl ement ))( c , o, i, v) : JS_FALSE) 

/* JSBool JS_SetEl ement( JSContext *cx, JSObject *obj , jsint idx, jsval *vp) */ 
#define JS_SetEl ement ( c , o, i, v) \ 

(mmEnv . setEl ement ? ( *(mmEnv . setEl ement ))( c , o, i, v) : JS_FALSE) 

/* JSBool JS_ExecuteScri pt ( JSContext *cx, JSObject *obj , unsigned short 
*scri pt , 

* unsigned int sz, jsval *rval ) */ 
#define JS_ExecuteScri pt ( c , o, s, z, r) \ 

(mmEnv . executeScri pt ? ( *(mmEnv . executeScri pt ) ) ( c , o, s, z, _T( FILE ), 

\ 

LINE , r) : JS_FALSE) 

/* JSBool JS_ReportError ( JSContext *cx, unsigned short *error, unsigned int 
sz) */ 

#define JS_ReportError ( c , e, s) \ 

(mmEnv . reportError ? ( *(mmEnv . reportError ) ) ( c , e, s) : JS_FALSE) 



/-> 

* Private data types, macros, and globals 

typedef struct j 

JSObject *libObj; 

JSBool (*defineFunction) (JSObject *libObj, unsigned short *name, JSNative 
call , 

unsi gned i nt nargs ) ; 
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unsigned short *(*val ueToStri ng) ( JSContext *cx, jsval v, unsigned int 
*pLength ) ; 

unsigned char *( *val ueToBytes )( JSContext *cx, jsval v, unsigned int 
*pLength ) ; 

JSBool (*val ueToInteger) (JSContext *cx, jsval v, long *lp); 
JSBool (*val ueToDoubl e) (JSContext *cx, jsval v, double *dp); 
JSBool (*val ueToBool ean) (JSContext *cx, jsval v, JSBool *bp); 
JSBool (*val ueToObject) (JSContext *cx, jsval v, JSObject **op); 
JSBool (*stri ngToVal ue )( JSContext *cx, unsigned short *b, unsigned int sz, 
jsval *vp); 

JSBool (*bytesToVal ue) (JSContext *cx, unsigned char *b, unsigned int sz, 
jsval *vp); 

JSBool (*doubl eToVal ue) (JSContext *cx, double dv, jsval *vp); 
unsigned short *(*objectType) (JSObject *obj); 

JSObject *(*newArrayObject) (JSContext *cx, unsigned int length, jsval *vp); 
long (*getArrayLength) (JSContext *cx, JSObject *obj); 
JSBool (*getEl ement) (JSContext *cx, JSObject *obj , unsigned int idx, 
jsval *vp) ; 

JSBool (*setEl ement) (JSContext *cx, JSObject *obj , unsigned int idx, 
jsval *vp); 

JSBool ( *executeScri pt )( JSContext *cx, JSObject *obj , unsigned short 
*scri pt , 

unsigned int sz, unsigned short *file, unsigned int lineNum, jsval 
*rval ) ; 

JSBool ( *reportError )( JSContext *cx, unsigned short *error, unsigned int 
sz); 

I MM_Envi ronment ; 

extern MM_Envi ronment mmEnv; 

// Declare the external entry point and linkage 
#ifdef _WIN32 

# ifndef _MAC 
// Windows 

declspect dllexport ) void MM_Ini tWrappert MM_Envi ronment *env, unsigned 

i nt envSi ze ) ; 

# else 

// Mac with MSVC++ Win32 portability lib 

extern void MM_InitWrapper( MM_Envi ronment *env, unsigned int envSize ); 

# end if 
#el se 

// Codewarrior 

# pragma export on 

extern void MM_InitWrapper( MM_Envi ronment *env, unsigned int envSize ); 

# pragma export off 
#endif 



#define MM_STATE \ 

/* Definitions of global variables */ \ 

MM_Envi ronment mmEnv; \ 

\ 

void \ 
MM_Ini tWrapper(MM_Envi ronment *env, unsigned int envSize) 

\ 
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char **envPtr = (char **)env; 

char **mmPtr = (char **) ( SmmEnv ) ; 

char **envEnd = (char **)((char *)envPtr + envSize); 

char **mmEnd = (char **)((char *)mmPtr + si zeof (MM_Envi ronment) ) ; 



extern void MM_Init(); 



\ 
\ 
\ 
\ 
\ 
\ 



\ 



/* Copy fields from env to mmEnv, one pointer at a time */ 
while (mmPtr < mmEnd && envPtr < envEnd) 
*mmPtr++ = *envPtr++; 



\ 
\ 
\ 
\ 
\ 



/* If env doesn't define all of mmEnv's fields, set extras to NULL */ 



\ 



/* Call user's MM_Init function */ 
MM_Init( ) ; 



while (mmPtr < mmEnd) 

*mmPtr++ = (char *)0; 



\ 
\ 
\ 
\ 
\ 
\ 



#endif /* _MM_JSAPI_H_ */ 

Sample implementation 

Included with this documentation is a set of files (Sample.zip for Windows, Sample.sit for 
Macintosh) that you can use to test the process of building a DLL. (You can download the file at 
www.macromedia. com/ go/jsapi_info_en) . 

To see how the process works without actually building the DLL, you can do the following: 

• Store the Sample.jsfl file in the Commands directory (see "Overview of the Macromedia Flash 
JavaScript API" on page 17). 

• Store the Sample.dll file in the External Libraries directory (see "How integrating C functions 
works" on page 369). 

• In the Flash authoring environment, select Commands > Sample. The trace statement in the 
JSFL file sends the results of the function defined in Sample.dll to the Output panel. 

This section discusses the development of the sample. In this case, the DLL contains only one 
function, which adds two numbers. The C code is shown in the following example: 

// Source code in C 

// Save the DLL or shared library with the name "Sample" 
#i include <windows.h> 
#include <stdlib.h> 

#i include "mm_jsapi.h" 

// A sample function 

// Every implementation of a Javascript function must have this signature 
JSBool computeSum( JSContext *cx, JSObject *obj , unsigned int argc, jsval 
*argv , jsval *rval ) 

{ 
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long a, b, sum; 

// Make sure the right number of arguments were passed in 
if (argc != 2) 
return JS_FALSE; 

// Convert the two arguments from jsvals to longs 
if ( JS_Val uefolntegertcx, argv[0], &a) = JS_FALSE || 
JS_Val uefoInteger(cx, argv[l], &b) == JS_FALSE) 
return JS_FALSE; 

/* Perform the actual work */ 
sum = a + b ; 

/* Package the return value as a jsval */ 
*rval = JS_Integerf oVal ue(sum) ; 

/* Indicate success */ 
return JS_fRUE; 

1 

After writing this code, build the DLL file or shared library, and store it in the appropriate 
External Libraries directory (see "How integrating C functions works" on page 369). Then create 
a JSFL with the following code, and store it in the Commands directory (see "Overview of the 
Macromedia Flash JavaScript API" on page 17). 

// JSFL file to run C function defined above 
va r a = 5 ; 
va r b = 10 ; 

var sum = Sampl e . computeSumt a , b); 

f 1 . trace( "T he sum of " + a + " and " + b + " is " + sum ); 

To run the function defined in the DLL, select Commands > Sample in the Flash authoring 
environment. 

Data types 

The JavaScript interpreter defines the following data types: 

• JSContext 

• JSObject 

• jsval 

• JSBool 

typedef struct JSContext JSContext 

A pointer to this opaque data type passes to the C-level function. Some functions in the API 
accept this pointer as one of their arguments. 

typedef struct JSObject JSObject 

A pointer to this opaque data type passes to the C-level function. This data type represents an 
object, which might be an array object or some other object type. 
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typedef struct jsval jsval 

An opaque data structure that can contain an integer, or a pointer to a float, string, or object. 
Some functions in the API can read the values of function arguments by reading the contents of a 
jsval structure, and some can be used to write the function's return value by writing a jsval 
structure. 

typedef enum { JS_FALSE = 0, JS_TRUE = 1 } JSBool 

A simple data type that stores a Boolean value. 

The C-level API 

The C-level extensibility API consists of the JSBool ( * J S N a t i ve ) function signature and the 
following functions: 

• JSBool JS_DefineFunction( ) 

• unsigned short *JS_Val ueToStri ng ( ) 

• JSBool JS_Val ueToInteger( ) 

• JSBool JS_ValueToDouble() 

• JSBool JS_ValueToBoolean( ) 

• JSBool JS_ValueToObject() 

• JSBool JS_Stri ngToVal ue ( ) 

• JSBool JS_Doubl eToVal ue( ) 

• JSVal JS_Bool eanToVal ue( ) 

• JSVal JS_BytesToValue( ) 

• JSVal JS_IntegerToValue( ) 

• JSVal JS_ObjectToValue() 

• unsigned short *JS_ObjectType( ) 

• JSObject *JS_NewArrayObject( ) 

• long JS_GetArrayLength( ) 

• JSBool JS_GetElement( ) 

• JSBool JS_SetEl ement ( ) 

• JSBool JS_ExecuteScri pt ( ) 
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typedef JSBool (*JSNative)(JSContext *cx, JSObject *obj, unsigned int 
argc, jsval *argv, jsval *rval) 

Description 

Method: describes C-level implementations of JavaScript functions in the following situations: 

• The cx pointer is a pointer to an opaque JSContext structure, which must be passed to some 
of the functions in the JavaScript API. This variable holds the interpreter's execution context. 

• The obj pointer is a pointer to the object in whose context the script executes. While the script 
is running, the this keyword is equal to this object. 

• The argc integer is the number of arguments being passed to the function. 

• The argv pointer is a pointer to an array of jsval structures. The array is argc elements 
in length. 

• The rva 1 pointer is a pointer to a single jsval structure. The function's return value should 
be written to * r v a 1 . 

The function returns JS_TRUE if successful; JS_FALSE otherwise. If the function returns 
JS_FALSE, the current script stops executing and an error message appears. 

JSBool JS_DefineFunction() 

Usage 

JSBool JS_Def i neFuncti on ( unsi gned short *name, JSNative call, unsigned int 
na rgs ) 

Description 

Method; registers a C-level function with the JavaScript interpreter in Flash. After the 
JS_Def i neFuncti on ( ) function registers the C-level function that you specify in the ca 1 1 
argument, you can invoke it in a JavaScript script by referring to it with the name that you specify 
in the name argument. The name argument is case-sensitive. 

Typically, this function is called from the MM_Ini t( ) function, which Flash calls during startup. 
Arguments 

unsigned short *name, JSNati ve ca 1 1, unsi gned int nargs 

• The name argument is the name of the function as it is exposed to JavaScript. 

• The ca 7 7 argument is a pointer to a C-level function. The function must return a JSBool , 
which indicates success or failure. 

• The nargs argument is the number of arguments that the function expects to receive. 
Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 
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unsigned short *JS_ValueToString() 

Usage 

unsigned short *JS_Val ueToStri ng( JSContext *cx, jsval v, 
unsigned int *pLength) 

Description 

Method; extracts a function argument from a j s v a 1 structure, converts it to a string, if possible, 
and passes the converted value back to the caller. 

Note: Do not modify the returned buffer pointer or you might corrupt the data structures of the 
JavaScript interpreter. To change the string, you must copy the characters into another buffer and 
create a new JavaScript string. 

Arguments 

JSContext *cx, jsval v, unsigned int *pLength 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The v argument is the jsval structure from which the string is to be extracted. 

• The pLength argument is a pointer to an unsigned integer. This function sets *pl ength equal 
to the length of the string in bytes. 

Returns 

A pointer that points to a null- terminated string if successful or to a nul 1 value on failure. The 
calling routine must not free this string when it finishes. 

JSBool JS_ValueTolnteger() 

Usage 

JSBool JS_Val ueToInteger( JSContext *cx, jsval v, long *lp); 
Description 

Method; extracts a function argument from a j s v a 1 structure, converts it to an integer (if 
possible), and passes the converted value back to the caller. 

Arguments 

JSContext *cx, jsval v, long *lp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The v argument is the jsval structure from which the integer is to be extracted. 

• The 1 p argument is a pointer to a 4-byte integer. This function stores the converted value 
in *1 p. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 
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JSBool JS_ValueToDouble() 

Usage 

JSBool JS_Val ueToDoubl e( JSContext *cx, jsval v, double *dp); 
Description 

Method; extracts a function argument from a j s v a 1 structure, converts it to a double (if 
possible), and passes the converted value back to the caller. 

Arguments 

JSContext *cx, jsval v, double *dp 

• The cx argument is the opaque JSContext pointer that passed to the JavaScript function. 

• The v argument is the jsval structure from which the double is to be extracted. 

• The dp argument is a pointer to an 8-byte double. This function stores the converted value 
in *dp. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 

JSBool JS_ValueToBoolean() 

Usage 

JSBool JS_Val ueToBool ean( JSContext *cx, jsval v, JSBool *bp); 
Description 

Method; extracts a function argument from a j s v a 1 structure, converts it to a Boolean value (if 
possible), and passes the converted value back to the caller. 

Arguments 

JSContext *cx, jsval v, JSBool *bp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The v argument is the jsval structure from which the Boolean value is to be extracted. 

• The bp argument is a pointer to a JSBool Boolean value. This function stores the converted 
value in *bp. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 



The C-level API 379 



JSBool JS_ValueToObject() 

Usage 

JSBool JS_Val ueToObjecU JSContext *cx, jsval v, JSObject **op); 
Description 

Method; extracts a function argument from a j s v a 1 structure, converts it to an object (if 
possible), and passes the converted value back to the caller. If the object is an array, use 
JS_GetArrayLength( ) and JS_GetEl ement( ) to read its contents. 

Arguments 

JSContext *cx, jsval v, JSObject **op 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The v argument is the jsval structure from which the object is to be extracted. 

• The op argument is a pointer to a JSOb j ect pointer. This function stores the converted value 
in *op. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 

JSBool JS_StringToValue() 

Usage 

JSBool JS_Stri ngToVal ue ( JSContext *cx, unsigned short *bytes, uint sz, jsval 
*vp) ; 

Description 

Method; stores a string return value in a j s v a 1 structure. It allocates a new JavaScript string 
object. 

Arguments 

JSContext *cx, unsi gned short *bytes, si ze_t sz, jsval *vp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The bytes argument is the string to be stored in the jsval structure. The string data is copied, 
so the caller should free the string when it is not needed. If the string size is not specified (see 
the sz argument), the string must be null-terminated. 

• The sz argument is the size of the string, in bytes. If sz is 0, the length of the null-terminated 
string is computed automatically. 

• The vp argument is a pointer to the jsval structure into which the contents of the string 
should be copied. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 
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JSBool JS_DoubleToValue() 

Usage 

JSBool JS_Doubl eToVal ue( JSContext *cx, double dv, jsval *vp); 
Description 

Method; stores a floating-point number return value in a jsval structure. 
Arguments 

JSContext *cx, double dv, jsval *vp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The dv argument is an 8-byte floating-point number. 

• The vp argument is a pointer to the jsval structure into which the contents of the double 
should be copied. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 

JSVal JS_BooleanToValue() 

Usage 

jsval JS_Bool eanToVal ue( JSBool bv); 
Description 

Method; stores a Boolean return value in a jsval structure. 

Arguments 

JSBool bv 

• The bv argument is a Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 
Returns 

A JSVal structure that contains the Boolean value that passes to the function as an argument. 

JSVal JS_BytesToValue() 

Usage 

JSBool JS_BytesToVal ue( JSContext *cx, unsigned short *bytes, uint sz, jsval 
*vp) ; 

Description 

Method; converts bytes to a JavaScript value. 
Arguments 

JSContext *cx, unsigned short bytes, uint sz, jsval *vp 

• The cx argument is the JavaScript context. 

• The bytes argument is the string of bytes to convert to a JavaScript object. 
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• The sz argument is the number of bytes to be converted. 

• The vp argument is the JavaScript value. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 

JSVal JS_lntegerToValue() 

Usage 

jsval JS_IntegerToVal ue( 1 ong Iv); 
Description 

Method; converts a long integer value to JSVal structure. 

Arguments 

Iv 

• The 7 v argument is the long integer value that you want to convert to a j s v a 1 structure. 
Returns 

A JSVal structure that contains the integer that passed to the function as an argument. 

JSVal JS_ObjectToValue() 

Usage 

jsval JS_ObjectToValue(JSObject *obj); 
Description 

Method; stores an object return value in a JSVal . Use JS_ NewArrayObjectt ) to create an array 
object; use JS_SetEl ementt ) to define its contents. 

Arguments 

JSObject *obj 

• The obj argument is a pointer to the JSObject object that you want to convert to a JSVal 
structure. 

Returns 

A JSVa 1 structure that contains the object that you passed to the function as an argument. 

unsigned short *JS_ObjectType() 

Usage 

unsigned short *JS_ObjectType( JSObject *obj); 
Description 

Method; given an object reference, returns the class name of the object. For example, if the object 
is a DOM object, the function returns "Document". If the object is a node in the document, the 
function returns "El ement". For an array object, the function returns "Array". 
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Note: Do not modify the returned buffer pointer, or you might corrupt the data structures of the 
JavaScript interpreter. 

Arguments 

J Subject *obj 

• Typically, this argument is passed in and converted using the JS_Val ueToObjectt ) function. 
Returns 

A pointer to a null-terminated string. The caller should not free this string when it finishes. 

JSObject * JS_NewArrayObject() 

Usage 

JSObject *JS_NewArrayObject( JSContext *cx, unsigned int length [, jsval *v ] ) 
Description 

Method; creates a new object that contains an array of JSVal s. 
Arguments 

JSContext *cx, unsi gned int length, jsval *v 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The 1 ength argument is the number of elements that the array can hold. 

• The v argument is an optional pointer to the j s v a 1 s to be stored in the array. If the return 
value is not null, v is an array that contains length elements. If the return value is nul 1 , 
the initial content of the array object is undefined and can be set using the 

JS_SetEl ement( ) function. 

Returns 

A pointer to a new array object or the value null upon failure. 

long JS_GetArrayl_ength() 

Usage 

long JS_GetArrayLength( JSContext *cx, JSObject *obj) 
Description 

Method; given a pointer to an array object, gets the number of elements in the array. 
Arguments 

JSContext *cx, JSObject *obj 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The obj argument is a pointer to an array object. 

Returns 

The number of elements in the array or -1 upon failure. 
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JSBool JS_GetElement() 

Usage 

JSBool JS_GetEl ement ( JSContext *cx, JSObject *obj , jsint idx, jsval *vp) 
Description 

Method; reads a single element of an array object. 
Arguments 

JSContext *cx, JSObject *obj, unsi gned int index, jsval *v 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The obj argument is a pointer to an array object. 

• The index argument is an integer index into the array. The first element is index 0, and the 
last element is index (length - 1). 

• The v argument is a pointer to a j s v a 1 where the contents of the jsval structure in the array 
should be copied. 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 

JSBool JS_SetElement() 

Usage 

JSBool JS_SetEl ement ( JSContext *cx, JSObject *obj , jsint idx, jsval *vp) 
Description 

Method; writes a single element of an array object. 
Arguments 

JSContext *cx, JSObject *obj , unsigned int index, jsval *v 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The obj argument is a pointer to an array object. 

• The index argument is an integer index into the array. The first element is index 0, and the 
last element is index (length - 1 ) . 

• The v argument is a pointer to a jsval structure whose contents should be copied to the 
jsval in the array. 

Returns 

A Boolean value: JS_TRJE indicates success; JS_FALSE indicates failure. 
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JSBool JS_ExecuteScript() 

Usage 

JS_ExecuteScri pt (JSContext *cx, JSObject *obj , unsigned short *script, 
unsigned int sz, jsval *rval) 

Description 

Method; compiles and executes a JavaScript string. If the script generates a return value, it returns 
in *rval . 

Arguments 

JSContext *cx, JSObject *obj, unsi gned short *scri pt, unsi gned int sz, jsval *rval 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function. 

• The obj argument is a pointer to the object in whose context the script executes. While the 
script is running, the this keyword is equal to this object. Usually this is the JSObject pointer 
that passes to the JavaScript function. 

• The script argument is a string that contains JavaScript code. If the string size is not specified 
(see the sz argument), the string must be null-terminated. 

• The sz argument is the size of the string, in bytes. If sz is 0, the length of the null-terminated 
string is computed automatically. 

• The rva 7 argument is a pointer to a single jsval structure. The function's return value is 
stored in *rval . 

Returns 

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. 
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